Project Best Practices task force

The project best practices task force intends to gather existing 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 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 an 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

• CI

• NOTICE

• License headers on all source files

• Build files

• Tests

• 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/aries-rfcs

  • https://github.com/hyperledger/sawtooth-rfcs (same in Ursa, Grid)

  • https://github.com/hyperledger/fabric-rfcs (evolution of sawtooth)

• Team structure, decision making - example https://github.com/hyperledger/sawtooth-rfcs/blob/main/text/0006-sawtooth-governance.md

Community

• Mailing list
  

• Discord Chat

• Public meetings

• Pull Request fast turnarounds

• 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

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 analysis (SAST) 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, scans, releasing

• Unit tests

• Integration tests

• Test coverage reporting

• See Automated Pipelines task force - https://github.com/hyperledger/toc/issues/44