Best Practices¶
The CLAS Software Working Group promotes the following software best practices.
- Accessibility
- Software should be maintained in a version-controlled git repository, fully readable to the collaboration. For example:
- publicly accessible without authentication
- in JLab's GitHub organization and its clas12 team, https://github.com/orgs/JeffersonLab/teams/clas12
- in JLab’s GitLab server under its clas12 directory, https://code.jlab.org/hallb/clas12
- Software should be maintained in a version-controlled git repository, fully readable to the collaboration. For example:
- Development
- A main, default branch in that same repository
- off which all standard releases are made
- which is managed only via pull/merge requests, requiring a passing CI build, w/ peer review/approval for multi-author projects
- Contributions
- commits should not be rewritten under a different author or project
- pull/merge requests should be single purpose
- usage of conventional commit messages is encouraged, to help keep commits small and focused
- Communications
- Github/Gitlab issues should be used to document known problems, feature requests, and planning.
- A main, default branch in that same repository
- Releases
- all software should follow semantic versioning
- releases should have release notes, documenting major changes, especially breaking changes
- backporting must be documented
- Binary Distributions
- should be transparently associated with source code version control tags
- should be supported by an open build system that can deploy those same binary distributions
- Core Components
- critical software components should not rely on a sole developer
- critical collaboration software should be managed and maintained by a core group
- Licensing
- all software should be licensed and copyrighted, preferably open source