Skip to content

Commit

Permalink
Built site for gh-pages
Browse files Browse the repository at this point in the history
  • Loading branch information
Quarto GHA Workflow Runner committed Dec 5, 2024
1 parent 72989fb commit 46948dd
Show file tree
Hide file tree
Showing 4 changed files with 128 additions and 63 deletions.
2 changes: 1 addition & 1 deletion .nojekyll
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
80f3b4ee
11813286
112 changes: 85 additions & 27 deletions im/github-organization-recs.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -206,11 +206,12 @@ <h2 id="toc-title">On this page</h2>

<ul>
<li><a href="#rationale" id="toc-rationale" class="nav-link active" data-scroll-target="#rationale">Rationale</a></li>
<li><a href="#site-github-user-vs.-organization" id="toc-site-github-user-vs.-organization" class="nav-link" data-scroll-target="#site-github-user-vs.-organization">Site GitHub “User” vs.&nbsp;“Organization”</a></li>
<li><a href="#naming-convention" id="toc-naming-convention" class="nav-link" data-scroll-target="#naming-convention">Naming Convention</a></li>
<li><a href="#organization-description-readme" id="toc-organization-description-readme" class="nav-link" data-scroll-target="#organization-description-readme">Organization Description &amp; README</a></li>
<li><a href="#administrators" id="toc-administrators" class="nav-link" data-scroll-target="#administrators">Administrators</a></li>
<li><a href="#organization-teams" id="toc-organization-teams" class="nav-link" data-scroll-target="#organization-teams">Organization “Teams”</a></li>
<li><a href="#example-organization---ble" id="toc-example-organization---ble" class="nav-link" data-scroll-target="#example-organization---ble">Example Organization - BLE</a></li>
<li><a href="#organization-description-readme" id="toc-organization-description-readme" class="nav-link" data-scroll-target="#organization-description-readme">Organization Description &amp; README</a></li>
<li><a href="#organization-teams" id="toc-organization-teams" class="nav-link" data-scroll-target="#organization-teams">Organization Teams</a></li>
<li><a href="#table-of-contents-repository" id="toc-table-of-contents-repository" class="nav-link" data-scroll-target="#table-of-contents-repository">Table of Contents Repository</a></li>
<li><a href="#github-organization-vs.-other-platforms" id="toc-github-organization-vs.-other-platforms" class="nav-link" data-scroll-target="#github-organization-vs.-other-platforms">GitHub Organization vs.&nbsp;Other Platforms</a></li>
</ul>
<div class="toc-actions"><ul><li><a href="https://github.com/lter/docs-network/issues/new" class="toc-action"><i class="bi bi-github"></i>Report an issue</a></li></ul></div></nav>
Expand Down Expand Up @@ -239,46 +240,103 @@ <h1 class="title">GitHub Organization Recommendations</h1>

<section id="rationale" class="level2">
<h2 class="anchored" data-anchor-id="rationale">Rationale</h2>
<p><a href="https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/about-organizations">GitHub Organizations</a> are a great way of centralizing many individual GitHub repositories under a common umbrella. Access to these repositories is easily shared with organization members and limits to this access can be implemented smoothly as desired across groups of users simultaneously. Organizations also “own” repositories which lessens the risk of accidental deletion. Websites created by repositories owned by the same organization have a URL with a shared root which greatly simplifies navigation around the ecosystem of products produced by an organization.</p>
<p>The LTER Network recommends each LTER site create a GitHub organization for itself and then encourage site staff and visiting researchers to house their repositories there rather than in their own profiles. There are many benefits of GitHub Organizations (including those outlined above) and we hope that you share our excitement for this potential new direction!</p>
<p>The LTER Network has followed our own advice and has a GitHub Organization which you can see <a href="https://github.com/lter">here</a>!</p>
<p><a href="https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/about-organizations">GitHub Organizations</a> are a great way of centralizing many individual GitHub repositories under a common umbrella. Access to these repositories is easily shared with organization members and limits to this access can be implemented smoothly across groups of users simultaneously. Organizations also “own” repositories which ensures that access to particular repositories cannot be lost with personnel changes.</p>
<p><strong>The LTER Network recommends each LTER site maintain a GitHub organization for itself</strong> and then encourage site staff and visiting researchers to house their repositories there rather than in their own profiles. There are many benefits of GitHub Organizations (including those outlined above) and we hope that you share our excitement for this potential new direction!</p>
<p>The LTER Network Office has followed our own advice and made a GitHub Organization which you can see <a href="https://github.com/lter">here</a>!</p>
</section>
<section id="site-github-user-vs.-organization" class="level2">
<h2 class="anchored" data-anchor-id="site-github-user-vs.-organization">Site GitHub “User” vs.&nbsp;“Organization”</h2>
<p>It may seem simplest to simply make a new GitHub <em>user</em> account for your site (or use your existing personal user account if you have one) but creating a ‘true’ organization confers several benefits that make it worthwhile:</p>
<ul>
<li>Organizations have better tools for granting edit access to groups of users
<ul>
<li>Through <a href="https://docs.github.com/en/organizations/organizing-members-into-teams/about-teams">teams</a> (more on this later)</li>
</ul></li>
<li>Organization membership is displayed on user profiles
<ul>
<li>So finding the site-level repositories from a user affiliated with the site is straightforward</li>
</ul></li>
<li>Centralizing code activity related to your site makes summarizing that work easier
<ul>
<li>E.g., during midterm reviews</li>
</ul></li>
<li>Websites hosted in an organization have a URL with a shared root
<ul>
<li>E.g., <a href="https://lter.github.io/ssecr/">lter.github.io/ssecr</a>, <a href="https://lter.github.io/scicomp/">lter.github.io/scicomp</a>, etc.</li>
</ul></li>
</ul>
<p>There are certainly other benefits you’ll likely experience after you take the plunge but hopefully this non-exhaustive list is persuasive as a reason to make the shift!</p>
</section>
<section id="naming-convention" class="level2">
<h2 class="anchored" data-anchor-id="naming-convention">Naming Convention</h2>
<p>We recommend adopting a common organization naming convention so that visitors to one organization can easily find the organization of another LTER site. Six sites currently have organizations and the general naming convention is to use the three letter site abbreviation in all caps followed by a hyphen and “LTER” (e.g., “MSP-LTER”).</p>
<p>Note that organization names can be changed as needed without breaking an individual user’s code but the link to GitHub-hosted websites/etc. will be changed if the organization name changes.</p>
</section>
<section id="organization-description-readme" class="level2">
<h2 class="anchored" data-anchor-id="organization-description-readme">Organization Description &amp; README</h2>
<p>We also recommend adding a short description of your site to the organization page, so that visitors have a big-picture overview of your site. In addition, the organization page is a great place to link to your site’s main website, your <a href="https://ror.org/search?query=LTER">Research Organization Registry (ROR)</a>, data catalog, or other platforms and build your online presence.</p>
<p>We also recommend that you create a README as a landing page for the Organization. To do this, create a public repository named “.github”. Add a “profile” folder and put “README.md” in that folder. The content of the README will then appear on your organization’s profile and will be the first thing visitors to the GitHub Organization will see.</p>
<p>We recommend adopting a common organization naming convention across sites so that visitors to one site’s organization can easily find the organization of another LTER site. There is some variance but most of the existing site organizations use the three letter site abbreviation in all caps followed by a hyphen and “LTER” (e.g., “MSP-LTER”). See below for a list of some of the site organizations.</p>
<ul>
<li>Arctic (ARC) GitHub: <a href="https://github.com/LTER-ARC">LTER-ARC</a></li>
<li>Beaufort Lagoon Ecosystems (BLE) Github: <a href="https://github.com/BLE-LTER">BLE-LTER</a></li>
<li>Central Arizona-Phoenix (CAP) GitHub: <a href="https://github.com/CAPLTER">CAPLTER</a> &amp; GitLab: <a href="https://gitlab.com/caplter">gitlab.com/caplter</a></li>
<li>Georgia Coastal Ecosystems (GCE) GitHub: <a href="https://github.com/GCE-LTER">GCE-LTER</a></li>
<li>Hubbard Brook (HBR) GitHub: <a href="https://github.com/HBR-LTER">HBR-LTER</a></li>
<li>Jornada Basin (JRN) GitHub: <a href="https://github.com/jornada-im">jornada-im</a></li>
<li>Kellogg Biological Station (KBS) GitHub: <a href="https://github.com/kbs-lter">KBS-LTER</a></li>
<li>Konza Prairie (KNZ) GitHub: <a href="https://github.com/knzlter">KNZLTER</a></li>
<li>Luquillo (LUQ) GitHub: <a href="https://github.com/LUQ-LTER">LUQ-LTER</a></li>
<li>Minneapolis-St.&nbsp;Paul (MSP) GitHub: <a href="https://github.com/MSP-LTER">MSP-LTER</a></li>
<li>Niwot Ridge (NWT) GitHub: <a href="https://github.com/NWTlter">NWTLTER</a></li>
<li>Northeastern Shelf (NES) GitHub Wiki: <a href="https://github.com/WHOIGit/nes-lter-ims/wiki">WHOIGit/nes-lter-ims/wiki</a></li>
<li>Palmer (PAL) GitHub: <a href="https://github.com/pal-lter">PAL-LTER</a></li>
<li>Plum Island Ecosystems (PIE) GitHub: <a href="https://github.com/PIE-LTER">PIE-LTER</a></li>
<li>Virginia Coast Reserve (VCR) GitHub: <a href="https://github.com/VCR-LTER">VCR-LTER</a></li>
</ul>
<p><strong>Note that organization names can be changed later without breaking <em>repository</em> links but <em>deployed website</em> links will need to be updated.</strong> For example, changing “github.com/lter/test” to “github.com/lter/my-website” will let existing repository links automatically redirect to the new location but “lter.github.io/test” will throw a 404 error from GitHub (should be “lter.github.io/my-website”).</p>
</section>
<section id="administrators" class="level2">
<h2 class="anchored" data-anchor-id="administrators">Administrators</h2>
<p>Members of an organization can be designated “owners” and they will then have access to all possible settings for the organization (including inviting new members, changing the organization name, or deleting the organization among other functions). <a href="https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/maintaining-ownership-continuity-for-your-organization">GitHub recommends adding more than one owner</a> because if only a single person has that power, access to the organization settings is entirely dependent on that person.</p>
<p>Members of an organization can be designated as “owners” and they will then have access to all possible settings for the organization (including inviting new members and managing repository settings among other powers). <a href="https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/maintaining-ownership-continuity-for-your-organization">GitHub recommends adding more than one owner</a> because if only a single person has that power, access to the organization settings is entirely dependent on that person.</p>
<p>We recommend adding the following people as owners of a site organization:</p>
<ul>
<li>Site Primary Investigator</li>
<li>Site Information Manager</li>
<li>At least one representative of the LTER Network Office</li>
<li>Site Information Manager (yourself!)</li>
<li>At least one representative of the LTER Network Office
<ul>
<li>Ideally either Marty Downs (<a href="https://github.com/marty-downs">marty-downs</a>) and/or Nick Lyon (<a href="https://github.com/njlyon0">njlyon0</a>)</li>
</ul></li>
</ul>
<p>Note that these people must all have a GitHub profile to be added as owners. Even if one of the prospective owners has no other need for a GitHub account, we feel it is worthwhile to have them create a GitHub profile for the sole purpose of allowing back-up access to the organization settings if that becomes necessary.</p>
</section>
<section id="organization-description-readme" class="level2">
<h2 class="anchored" data-anchor-id="organization-description-readme">Organization Description &amp; README</h2>
<p>We also recommend adding a short description of your site to the organization page, so that visitors have a big-picture overview of your site. In addition, the organization page is a great place to link to your site’s main website, your <a href="https://ror.org/search?query=LTER">Research Organization Registry (ROR)</a>, data catalog, or other platforms and build your online presence.</p>
<p>We also recommend that you create a README as a landing page for the Organization. To do this, create a public repository named “.github”. Add a “profile” folder and put “README.md” in that folder. The content of the README will then appear on your organization’s profile and will be the first thing visitors to the GitHub Organization will see. See the following as an example of this structure: <a href="https://github.com/lter/.github">github.com/lter/.github</a></p>
</section>
<section id="organization-teams" class="level2">
<h2 class="anchored" data-anchor-id="organization-teams">Organization “Teams”</h2>
<p>GitHub organizations control access to repositories in a slightly different way than repositories owned by individual users. In a user-owner repository, other profiles can be granted access and as each person is added, their level of access is decided by the profile that owns the repository. In an organization context however, access is controlled by <a href="https://docs.github.com/en/organizations/organizing-members-into-teams/about-teams">Organization Teams</a>. Instead of people being granted access to repositories, teams are granted access to repositories. Users are then added to team(s) as appropriate and their level of access is dictated by <a href="https://docs.github.com/en/enterprise-server@3.7/organizations/managing-user-access-to-your-organizations-repositories/repository-roles-for-an-organization">the access of the team</a>. Note that only organization owners have the power to create teams or modify the level of access granted to existing teams.</p>
<p>We recommend creating the following teams:</p>
<h2 class="anchored" data-anchor-id="organization-teams">Organization Teams</h2>
<p>GitHub organizations handle access to particular repositories via <a href="https://docs.github.com/en/organizations/organizing-members-into-teams/about-teams">teams</a>. Normally, to share a repository you invite particular users to a given repository from the settings page of that repository. In an organization context, you do the following:</p>
<ol type="1">
<li>Create a team</li>
<li>Add all relevant organization members to that team
<ul>
<li>Note that they <em>must</em> be organization members</li>
</ul></li>
<li>Add all relevant repositories to that <em>team</em>
<ul>
<li>When you do this you can choose the level of access all team members have to that repository</li>
</ul></li>
</ol>
<p>This has a few distinct advantages relative to the non-organization method of sharing access.</p>
<ul>
<li>Users gain access to team repositories without needing to accept a time-sensitive invite</li>
<li>When you make a new repository that falls under the purview of an existing team, it takes one action to empower all members of the team to access that repository</li>
<li>You can still add users to specific repositories in the way you normally would!
<ul>
<li><strong>“Admin” team</strong> including everyone at the LTER site that should have admin-level access to all repositories (i.e., can change repository-level settings)</li>
<li><strong>“Maintain” team</strong> including all lead researchers who need access to non-destructive actions in repositories (i.e., most repository-level settings)</li>
<li><strong>“Write” team</strong> including everyone who has any need to write any amount of code (i.e., no settings access but able to add/change code in a repository)</li>
<li>So no lost functionality by embracing teams</li>
</ul></li>
</ul>
<p>You may also want to create additional teams for active research or lab groups that have many repositories where a consistent set of profiles will need access to all of those repositories.</p>
<p>As new repositories are added to the organization, an organization owner will need to add teams to those repositories (so that people in each team have the correct level of access to that repository).</p>
<p>Note that only organization owners have the power to create teams or modify the level of access granted to existing teams. If a given research group has two or more repositories in the organization we recommend creating a team for that group to streamline access going forward. Consider the <a href="https://github.com/orgs/lter/teams">teams in the LTER Network GitHub organization</a> as an example for how you might structure your site’s organization.</p>
</section>
<section id="example-organization---ble" class="level2">
<h2 class="anchored" data-anchor-id="example-organization---ble">Example Organization - BLE</h2>
<p>The <a href="https://github.com/BLE-LTER">Beaufort Lagoon Ecosystem GitHub Organization</a> is a phenomenal example of everything we just described above! Check out their organization for a nice example of how one site went about setting up an Organization for themselves.</p>
<section id="table-of-contents-repository" class="level2">
<h2 class="anchored" data-anchor-id="table-of-contents-repository">Table of Contents Repository</h2>
<p>Finally, we recommend creating a ‘table of contents’ repository when you create your site organization. It might seem excessive when you only have a handful of repositories but starting one early will make it easier to keep an eye on how repositories are organized within your organization (including repository naming conventions and use of <a href="https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics">GitHub topics</a>)</p>
<p>The LTER Network organization index repository can be found here: <a href="https://github.com/lter/lter_github-index?tab=readme-ov-file#readme">github.com/lter/lter_github-index</a> and is directly linked from our organization-level README to make it easier for visitors to find/use that index.</p>
</section>
<section id="github-organization-vs.-other-platforms" class="level2">
<h2 class="anchored" data-anchor-id="github-organization-vs.-other-platforms">GitHub Organization vs.&nbsp;Other Platforms</h2>
Expand Down
Loading

0 comments on commit 46948dd

Please sign in to comment.