Page History
| Table of Contents |
|---|
Version History
| 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!) |
Definitions
| 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. |
| 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. |
...
- slac-epics
- Name is still undecided. Other options: slac-epics-support, slac-epics-infra
- Components that do not belong in slac-epics-apps, but depend on the EPICS build system and/or EPICS base
- Examples:
- EPICS base
- EPICS modules
- EDM
- ALH
- eco_tools
- Striptool
- Gateway
- eget services
- slac-epics-apps
- EPICS applications of all kinds, usually they will be specific to a part of the lab rather than shared
- Examples:
- EPICS IOCs from all directorates, like EED and LCLS.
- EPICS HLAs
- PyDM and EDM screens
- Matlab code that uses EPICS
- NOTE (5/1/24): Likely want to merge this with slac-epics
- slaclab
- Everything else.
...
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.
GitHub Pages and READMEs
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:
- https://github.com/pcdshub (Note the README.md at the top of the page)
- https://pcdshub.github.io/ (Note the sidebar with links to the slaclab org)
- Source code: https://github.com/pcdshub/pcdshub.github.io
- Provides a summary of some of their projects
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.
Licenses
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.
...
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.
...
Other aspects to consider
These are workflow-specificThis 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.
Repository naming
Should we standardize for repository naming or keep each team to define them freely? Use cases:
...
Overview
Content Tools