Project Best Practices task force

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, with links to 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/ and follow-on targeted task forces may be proposed.

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 required 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:

• Switching '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, 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

• RFC process for driving consensus and agreement on project decisions, features, design, etc. Examples:

  • https://github.com/hyperledger/aries-rfcs

  • 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 targeted for users and another targeted for contributors/maintainers?
  

• Discord Chat - important to strike a balance between too few and too many chat channels

• Public meetings - regular cadence

• Pull Requests - quick review turnarounds are appreciated

• Contributing docs - examples:

  • https://wiki.hyperledger.org/display/BESU/Contributing

  • https://github.com/hyperledger/cacti/blob/main/CONTRIBUTING.md

  • https://hyperledger-fabric.readthedocs.io/en/latest/CONTRIBUTING.html

  • https://wiki.hyperledger.org/display/indy/How+to+Contribute

  • https://hyperledger.github.io/firefly/contributors/

  • https://github.com/hyperledger/iroha/blob/main/CONTRIBUTING.rst

• NOTE - Perhaps common "contributing" content can be aggregated so that each project doesn't re-invent.

Security - add link to security task force

• Named security contacts per project (at least two)

• Security issue reporting process defined in SECURITY.md

• Security issue disclosure process - see task force https://github.com/hyperledger/toc/issues/48

• Leverage automated scans

  • linters

  • Software Composition Analysis dependency scans, e.g. Dependabot, Govulncheck (depends on language) 

  • Static Application Security Testing (SAST) aka static analysis scans, e.g. CodeQL, Snyk
    

• Keep dependencies up to date (e.g. Dependabot)

• Security audits for Graduated project major releases

• Review OpenSSF secure developer guide

• Review and obtain OpenSSF Best Practices Badge - criteria

• 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

• 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 release

• 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 - see Security section, more comprehensive scans can be run nightly instead

• 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 to simplify cherry picks and backports.

  • Example guidance - https://hyperledger-fabric.readthedocs.io/en/latest/github/github.html