Confluence will be unusable 23-July-2024 at 06:00 due to a Crowd upgrade.
This document moved to https://docs.google.com/document/d/1Ks9pfJyXlF7AjcGII_E_VFPK0jAzSxV0uBHzEIgY-t0/edit?usp=sharing. This is now deprecated.
Version | Date | Description of Changes |
---|---|---|
v0.0 | 4/??/24 | Initial draft work by Marcio and Jeremy |
v0.1 | 5/2/24 | Applied changes from last meeting. Made note of "interface" GitHub organizations, removed lcls-daq from the organization list, noted down additional discussion points about team setup. |
v0.2 | 5/3/24 | Added section about READMEs and GitHub pages. Added note that the "Other aspects to consider" is mostly noting capabilities that we probably want to apply in a more localized way. (we don't want to enforce a certain branching workflow for the whole lab!) |
v0.3 | 5/3/24 | Added section on security, for discussion in next meeting. |
Term | Description |
---|---|
Organization | A location on GitHub where many repositories and teams can be stored. Translates into a URL when browsing or cloning a repository. |
Team | A group of users having common access permissions to one or more repositories. Can be hierarchical. |
Working Copy | A clone of a Git repository that you can edit and compile. |
Repository | A location where Git history and code are stored. These are added as "remotes" on a local working copy. |
GHE | GitHub Enterprise |
HLA | High-Level Applications |
Fork | A copy of a repository from one organization to another. For example, github.com/slac-epics/asyn would be a fork of github.com/epics-modules/asyn. GitHub keeps track of forks so the upstream code has the link clearly visible. |
Upstream | Repository that is the original basis of a fork. |
NDA | Non-disclosure Agreement |
GitHub Enterprise (GHE) can support multiple organizations , each having any number of repositories, and also supporting a number of teams , providing different roles with distinct privilege within those repositories. We would like to maintain a relatively small number of GHE organizations at SLAC, and offer some guidelines for naming those organizations, teams and other related aspects of GHE.
slaclab is the organization that is the default starting point for all repositories maintained by SLAC. When thinking about the right place to create a new repository, the first answer is slaclab.
URL: https://github.com/slaclab
User access to this organization will probably be handled by SSO with the GitHub Enterprise account, meaning that if you already have an SLAC account, your access should be automatically allowed. Individuals leaving SLAC will have their account removed from GHE teams, having no access to those SLAC repositories that were formerly available. Certain employees maintain a working status at SLAC after their departure, with their login accounts remaining active. Their status within specific GHE teams would be decided by those remaining team members based on the individual's working agreement.
Questions to be answered:
slac-sandbox is an organization for hosting repositories that will be short-lived, like prototypes, code practice, and proof of concept. It is ok if a repository in slac-sandbox is transferred to slaclab if it makes sense.
We discourage people from creating sandbox repos related to work at SLAC in their personal GitHub accounts because the repositories could have value for SLAC in the future, even after the author leaves SLAC.
To keep the number of organizations small, new ones will be created according to the following guidelines:
This is just an example of organizations that currently exist at the present date. This list is not intended to keep track of all recognizable SLAC organizations and will not be updated in the future.
Organizations at SLAC that are accepted to the GitHub Enterprise umbrella will have:
Concerns when using GitHub Enterprise:
We understand that repositories under NDA may need to be outside GitHub Enterprise and, maybe, outside GitHub at all because organization administrators can't see its contents. Projects with DoD is an example.
Note that if you decide to go outside GitHub Enterprise, you lose all the advantages and will be on your own regarding administration of the organization. SLAC IT still may need to be involved regarding, for example, CI/CD jobs with SLAC hosted runners. There's a risk that IT may deny authorization and recommend the repository to be transferred to one organization in GitHub Enterprise.
FOR THE NEXT MEETING:
What it means if you split off into your own org within the enterprise instance:
I didn't understand these arguments.
GitHub doesn't provide a hierarchical structure for repository names, which means there is a possibility of name collisions when working in an organization with thousands of repositories. This document will not require specific naming rules, but offers guidelines for consistent naming that everyone can follow.
This document provides only a guideline for defining Teams in GitHub. How to organize Teams is not a requirement.
GitHub does support a hierarchical structure for teams, so repositories can be associated and aligned with a team hierarchy. The unique rule that is a requirement is that every repository must have a responsible Team. Repositories with one single individual as admin are only allowed in the slac-sandbox organization.
Naming could be abbreviated by Directorate-Department, for example, excluding the division if this makes sense. Avoid department acronyms though, as they may repeat inside different directorates. Another idea for naming hierarchical teams:
This is a very high-level example, only meant to show the hierarchy. All models can coexist because each repository can receive multiple teams and individuals.
As GitHub doesn't allow the distribution of repositories in a hierarchy like file systems do, one way to ease the search is by the use of Topics. Topics are like labels that can be set in each repository. A repository can have multiple Topics.
Once this is set, if you are interested in LLRF, for example, you would search by the LLRF Topic and see only the repositories related to that Topic.
Topics cross organizations in all GitHub. For example, checking the rtems topic returns https://github.com/topics/rtems. slaclab is one organization that shows up in the search results, but there are others.
At this moment GitHub allows for searching a Topic in one single organization or all organizations available in GitHub. There's no way to configure a search for a group of organizations. To improve the success in searches we suggest prepend "slac-" to all our Topics, like slac-timing, slac-atca, slac-llrf, etc. This way we ensure that a broad search in GitHub would bring repositories related only to organizations related to SLAC.
Currently we have 2 ticket systems in use for software development/bug tracking: CATER and Jira. GitHub brings its own ticket system called Issues.
CATER won't go away for a long time. So, what do we do regarding Jira and GitHub issues? The use cases could be:
Do we want to keep track of tickets in 3 different tools?
NOTE (5/1/24): Jerry K. indicated that EED is looking to move away from Jira. Other groups that have a heavier dependence on Jira may not want to move away.
Overall, this seems like a department-specific decision rather than one that can be made for the entire lab.
If we end up creating multiple different organizations for SLAC-related projects, how do we keep track of things? A potential solution to this issue is to use GitHub organization READMEs and GitHub pages for organization level documentation.
We could create an organization-level README on slaclab that contains links to other SLAC orgs and some basic information. We could also create a documentation page for the entire slaclab org that contains links to and information about relevant GitHub organizations and projects.
The pcdshub organization is a good example of this type of setup:
GitHub pages simply publishes HTML. They can either be written manually or generated with a software package like Spinx or Hugo.
In the above example, pcdshub.github.io is using Sphinx as the documentation generator and ReStructured Text for the source files.
In TID we've been following SLAC's legal request of adding a specific LICENSE file to each repository's top directory, plus a disclamer text in all .c, .cpp., .h, .hpp, .py, .vhd, etc files. There's a Python script that we run that do this automatically: https://github.com/slaclab/surf/blob/pre-release/scripts/apply_slac_license.py. As this comes from SLAC legal, I believe that this would be extended to all code available in SLAC's GitHub organizations.
The problem arises for external code that we fork in our repos. It is very common that the forked code has its own license that we can't modify. TID directors' orientation in this case is that the repository must be made private.
I believe that we need to talk with SLAC legal again to verify more use cases.
NOTE (5/1/24): SLAC legal is probably concerned about licensed code from other sources (i.e. vxWorks), not open source software. It is probably fine to keep open source projects we fork public.
Some thoughts about security:
All staff that needs to write to repositories under the the GitHub Enterprise umbrella will attend a training session to learn about general standards and recommended practices described in this document. At the present date this training is still under development. Should it be in the staff STA?
This section covers workflow specific guidelines for the usage of GitHub enterprise. These are not intended to be applied lab wide! Instead, these serve as examples of controls that may be applied on a per-department/group/division basis.
Should we standardize for repository naming or keep each team to define them freely? Use cases:
Should the entire SLAC follow the same workflow, with standard names for branches, and standard rules for using each branch? What if different departments have conflicting requirements?
Settings > Rules > Rulesets
[0-9]+.[0-9]+.[0-9]+
The work outlined here is outside of the scope of this document and should probably be done on a per directorate/department/group basis.
ipmiComm and ek9000 module could be used as the reference implementation for these things.
These two modules should implement most or all of the recommended CI checks and whatnot, and adhere to the standards we define.