The project best practices task force intends to gather existing project guidelines and best practices in one central place, and identify gaps that may be addressed in parallel or future task forces.
The expected output is a centrally located reference document to make project maintainers and contributors aware of the universe of project related guidelines and best practices, and the various resources available to them for further learning and adoption.
This wiki page is intended for initial brainstorming and collaboration. Eventually the task force output will be published at https://toc.hyperledger.org/.
Maintainers guidelines includes guidance around:
MAINTAINERS.md with active and emeritus maintainers
Maintainer responsibilities
Becoming a maintainer
Removing a maintainer, see also inactivity policy
Common Repository Structure includes guidance around repository files such as:
README.md
CONTRIBUTING.md
LICENSE
CODE_OF_CONDUCT.md
SECURITY.md
CHANGELOG.md
MAINTAINERS.md
NOTICE
License headers on all source files
Build files
CI and test files
No executable binaries
Inclusive naming includes guidance around:
Master to main branch
Inclusive naming conventions
Inclusive language statement
Project Incubation Exit Criteria includes guidance applicable to any Incubation or Graduated project:
Legal - Apache 2 license
Community support - Active and diverse contributors
Test coverage - Automated unit and integration test suites
Documentation - see Documentation section below
Infrastructure - see Common Repository Structure and Community sections
Security - see Security section below
OpenSSF Best Practices Badge - https://bestpractices.coreinfrastructure.org/en
Project Governance
RFC process examples:
https://github.com/hyperledger/sawtooth-rfcs (same process in Ursa, Grid)
https://github.com/hyperledger/fabric-rfcs (evolution of sawtooth RFC process)
Team structure, decision making - example https://github.com/hyperledger/sawtooth-rfcs/blob/main/text/0006-sawtooth-governance.md
Community
Mailing lists
Discord Chat
Public meetings
Pull Request fast turnarounds
Contributing docs - examples:
Security - add link to security task force
Named security contacts
Security issue reporting process (defined in SECURITY.md)
Security issue disclosure process - see task force https://github.com/hyperledger/toc/issues/48
Automated scans
linters
Software Composition Analysis dependency scans (e.g. Dependabot, Govulncheck)
Static Application Security Testing (SAST) aka static analysis scans (e.g. CodeQL, Snyk)
Keep dependencies up to date (e.g. Dependabot)
Major release security audits
OpenSSF secure developer guide - https://github.com/ossf/wg-best-practices-os-developers/blob/main/docs/Concise-Guide-for-Developing-More-Secure-Software.md
OpenSSF Best Practices Badge criteria - https://bestpractices.coreinfrastructure.org/en/criteria/0
Security Artifact Signing - proposed task force - https://github.com/hyperledger/toc/issues/49
Documentation - add link to Documentation and Onboarding task forces
User guide including Getting Started / Tutorial
Developer guide including coding guidelines, build instructions, test instructions
Application developer guide
- Recommended documentation platform?
Releases
Release taxonomy - either SemVer or CalVer
Documented release strategy, release process, branch strategy
Long-term support (LTS) release strategy - example https://github.com/hyperledger/fabric-rfcs/blob/main/text/0005-lts-release-strategy.md
Release artifacts - attached to GitHub release, docker images in GitHub Packages versus Dockerhub
CI
GitHub Actions recommended
Pull request checks
DCO
Unit tests
Integration tests
- Scans (more comprehensive scans can be nightly)
- Release actions
Test coverage reporting
See Automated Pipelines task force - https://github.com/hyperledger/toc/issues/44
GitHub
Use .github/settings.yml so that repository settings can be managed and tracked via pull requests
Recommended initial repository settings, e.g. Repository options, Branch protection rules
Rebase merging is preferred over Merge commits and Squash merging to keep commit history clean (assuming contributors squash/amend their own pull requests)
Although there are often multiple paths to achieve an outcome in git and GitHub, there is value in defining a suggested path, both for the benefit of new GitHub users, and for the sake of project consistency.
Examples - amending commits versus squashing commits, Mergifyio for simplifying cherry picks and backports.
Example guidance - https://hyperledger-fabric.readthedocs.io/en/latest/github/github.html