You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 48 Next »

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.  Follow-on targeted task forces may be proposed.


NOTE: This wiki page is intended for initial brainstorming and collaboration. Eventually the task force output will be published at https://toc.hyperledger.org/.


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

  • TODO - Clarify maintainer roles and responsibilities, e.g. prioritize pull request reviews (Stephen)


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

  • Optionally use GitHub Action DCI-Lint


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


Community


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

  • Review, respond, and act on reported security vulnerabilities

  • 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

  • Pin dependencies and keep dependencies up to date,  e.g. using Dependabot, although be wary of auto-upgrades and look for malware.

  • Engage with Hyperledger staff on possibility of security audits for Graduated project major releases, address audit results and socialize

  • Review OpenSSF secure developer guide and OpenSSF overview presentation to TOC (charts, replay)

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

  • User guide including Getting Started / Tutorial

  • Project developer guide including coding guidelines, build instructions, test instructions

  • Application developer guide

  • Recommended documentation platform?


Project management

  • Maintain a written project roadmap
  • Create, clarify, and label issues in Github for contributors
  • Review, triage, comment on, and close Github issues


Releases

  • Follow an established Release taxonomy - either SemVer or CalVer

  • Document release strategy, release process, branch strategy (one branch per major.minor release works well so that it can be maintained in isolation with major.minor.patch releases)

  • 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

  • Keep CI clean and green at all times, address failures and flakes

  • 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

  • Use recommended repository settings as a starting point, 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.

  • No labels