Definitions

GitHub Organization

Analysis of proposals

We've analyzed different ideas:

• Single organization for all the code created at SLAC:
  • We tried this and soon we started to face problems with naming conflicts.
  • To solve this we would need to modify the name of the repositories appending something that would group them. For example, all EPICS support modules would have "epics-" prepended. This way asyn would become epics-asyn.
  • The naming change was not ideal because we would like to fork an external module and have the name coincide with the upstream code.

Given that slaclab has hundreds of repositories, a naming conflict was very probable. We decided that we needed some level of repository grouping without creating too many repositories.

One idea of grouping would be to have one GitHub organization per SLAC directorate. This idea was abandoned because:

• It creates a virtual wall, psychologically discouraging collaboration between directorates.
• It breaks related repos into different organizations. For example, EPICS modules would be spread in different GitHub organizations.
• It difficults transfer of ownership if this ever happens.

For managing repositories in a per-directorate basis, a best approach would be to use GitHub teams.

Current proposal

• 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
    • EDM
    • ALH
    • 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
• slac-daq
  • The code is currently at slac-lcls and it is all related to DAQ data source and data-consuming software.
• slaclab
  • Everything else.

Pros and cons for having this model:

• Pros
  • Separate from slaclab org creating less name contention.
  • Only people who need access will be added to each organization.
  • Already used for our EPICS software (currently mirrors, though).
  • Easy to find related code because the code is grouped in an organization with an easily identifiable name.
• Cons/Problems to Solve
  • Another organization to manage; need to mirror teams and such, which seems to be easily managed with GHE.

Exceptions to consider

A few repositories already receive collaboration from other labs around the world. Moving them to another organization would impact people outside SLAC. For these cases, we might have to keep them untouched. Examples:

• EPICS archiver: has its own organization - https://github.com/archiver-appliance. This organization has 8 repositories.
• PyDM and NALMS could fit in slac-epics (or slac-epics-infra, slac-epics-support), but their location in slaclab is already used by many outside SLAC.

GitHub Teams

The most obvious approach for organizing teams in GitHub would be to use its hierarchical team configuration to mimic what we have at SLAC. Using the embedded group in TID as an example:

This way, repositories maintained by a specific group can easily be configured to the correspondent team.

The easiest way to configure this model is to have the group leaders add their group members to the correct team in GitHub. This would share the effort among several people, reducing the load.

Another model that can use GitHub Teams is creating teams per system. Examples:

• Timing team: responsible for everything that is related to the timing system.
• EPICS team: responsible for everything that is related to EPICS.

Both models can coexist as permission to individual repositories can receive multiple teams and individuals.

GitHub Topics

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, so having more than one organization doesn't impact this search mechanism. 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 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 could 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.

GitHub Issues

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:

1. CATER is kept as it is used today. No changes.
2. GitHub issues for SLAC maintained repositories that have external collaborators.
3. GitHub issues for tickets clearly related to one single repository.
4. Jira for tickets that cross multiple repositories or that are unrelated to work for any repository. Could GitHub Projects be used for this, instead?

Do we want to keep track of tickets in 3 different tools? 

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.

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.

Other aspects (should they be standardized among all SLAC?)

Repository Naming

Should we standardize for repository naming or keep each team to define them freely? Use cases:

If we have a single organization:

• Keep names identical to upstream software?
• Prefix EPICS modules with epics-?
• Prefix extensions with extension-? or epics-?
• Prefix IOC applications with ioc-?

If we have slac_epics or directorate orgs:

• No module prefix
• No extension prefix
• Prefix IOC applications with ioc-?

Standard Rulesets

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

• Mirror TID-ID workflows
  • Git workflow for the Embedded Group
• Match branches:
  • main
  • pre-release
  • Release tags (in the format [0-9]+.[0-9]+.[0-9]+ 
    • NOTE: GitHub uses fnmatch, not regexp for this matching.
• Allow bypass:
  • Maintainers and repository owners
• Restrict creations
• Restrict updates
• Restrict deletions
• Require a pull request before merging
  • Require at least 1 approval before merge
• Require status checks to pass
  • Only if CI is enabled

Future Work

Not for the current organization proposal.

Establish Standards for Locally Developed C/C++ Projects

ipmiComm and ek9000 module should 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.

• GitHub actions for CI. Verify things compile to avoid broken code being merged.
• Set -Werror, minimize ignored warnings
  • Define standard set of enabled/disabled warnings for C/C++ projects
• Some level of automated testing, (OPTIONAL)
  • Testing should be run with a runtime analyzer too
    • asan
    • valgrind
  • Testing may not always be possible due to the nature of EPICS
• Static code analysis with clang-tidy
  • Define standard set of clang-tidy checks
• Code formatting with clang-format (OPTIONAL)
  • Define standard clang-format configuration (ideally one that closely matches our current, most common style)

Establish Standards for Documentation

• Generate documentation using:
  • Sphinx (Restructured Text) (any, but mostly Python)
  • Doxygen or clang-doc (C, C++)
  • LaTeX (any)
• Publish documentation to GitHub pages
  • See asyn and friends for a CI setup here: https://github.com/epics-modules/asyn/blob/master/.github/workflows/publish-docs.yml

Establish Standards for Commit Names

• Git workflow for embedded group does not define commit naming guidelines
• Perhaps we want to define some, like PCDS does?
• See https://pcdshub.github.io/development.html#commit-guidelines

Document Contribution Workflow on GitHub Pages

• Again, like PCDS does: https://pcdshub.github.io/development.html
• They also briefly describe their various repositories so newbies can figure out where to find what.
• Links in the side bar too!!