Task Force objective
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.
Task Force expected output
The expected output is a centrally located concise reference document to make project maintainers and contributors aware of the universe of project related guidelines and best practices, along with links to the various resources available to them for further learning and adoption.
NOTE: This wiki page is intended for initial brainstorming and collaboration. Eventually the task force output will be published at https://toc.hyperledger.org/ and follow-on targeted task forces may be proposed.
Proposed project best practices (with links to existing content, related task forces, etc)
Maintainers guidelines includes guidance and examples around:
MAINTAINERS.md defining active and emeritus maintainers
Maintainer responsibilities
Becoming a maintainer
Removing a maintainer, see also inactivity policy
Common Repository Structure includes guidance around required and recommended repository files such as:
- Required
README.md
CONTRIBUTING.md
LICENSE
CODE_OF_CONDUCT.md
SECURITY.md
CHANGELOG.md
MAINTAINERS.md
- CI files
- Recommended
NOTICE
License headers on all source files
Build files
Test files
Inclusive naming includes guidance around:
Switching 'master' to 'main' branch
Inclusive naming conventions
Inclusive language statement
Project Incubation Exit Criteria includes high level guidance applicable to any Incubation or Graduated project:
Legal - Apache 2 license
Community support - Active and diverse contributors, plus see Community section below
Test coverage - Automated unit and integration test suites
Documentation - plus see Documentation section below
Infrastructure - plus see Common Repository Structure and Community sections
Security - plus see Security section below
OpenSSF Best Practices Badge - https://bestpractices.coreinfrastructure.org/en
- NOTE - As the TOC comes to consensus on more best practices, we could add those to Project Incubation Exit Criteria.
Project Governance
Use an RFC process (or similar process) for driving consensus and tracking agreement on project major decisions, features, design, etc. 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 - perhaps one project mailing list targeted for users and another targeted for contributor/maintainer discussion?
Discord Chat - important to strike a balance between too few and too many chat channels
Public meetings - on a regular cadence
- Meetups
- Workshops - Combination of in person (e.g. Global Forum), virtual, and recorded
Pull Requests - quick review turnarounds are appreciated and encourage future contributions
Contributing docs - examples:
- NOTE - Perhaps common "contributing" content can be aggregated so that each project doesn't have to re-invent and re-document.
Security - see also 2022 security task force
Provide named security contacts per project (at least two contacts)
Define security issue reporting process in SECURITY.md with reference to Hyperledger reporting process
Follow security issue disclosure process - see Disclosure task force
Leverage automated scans, tooling depends on language but usually includes some combination of:
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. using Dependabot
Schedule security audits for Graduated project major releases
Review and obtain OpenSSF Best Practices Badge - criteria
Sign release artifacts (TBD) - see proposed Security Artifact Signing task force
Documentation - see also Documentation task force and Onboarding task forces
User guide including Getting Started / Tutorial
Project developer guide including coding guidelines, build instructions, test instructions
Application developer guide
- Recommended documentation platform?
Releases
Follow an established Release taxonomy - either SemVer or CalVer
Document release strategy, release process, branch strategy
Document Long-term support (LTS) release strategy - example https://github.com/hyperledger/fabric-rfcs/blob/main/text/0005-lts-release-strategy.md
- Use Github actions to automate release process, e.g. publish artifacts and release notes upon drafting a GitHub release
Release artifacts - attached to GitHub release, docker images in GitHub Packages versus Dockerhub?
Continuous Integration (CI)
GitHub Actions is the recommended CI platform
Pull request checks
DCO
Unit tests
Integration tests
- Scans - see Security section, more comprehensive scans can be run nightly instead
Test coverage reporting - run on-demand or nightly
See proposed Automated Pipelines task force
GitHub suggestions
Define repository settings in .github/settings.yml so that they can be managed and tracked via pull requests
Recommended initial repository settings, e.g. Repository options, Branch protection rules (TBD by TOC and Hyperledger staff)
Rebase merging is preferred over Merge commits and Squash merging to keep commit history clean (assuming contributors squash/amend their own pull requests) - opinion or best practice?
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 to simplify cherry picks and backports.
Example guidance - https://hyperledger-fabric.readthedocs.io/en/latest/github/github.html