Versions Compared

Old Version 21

changes.mady.by.user David Enyeart

Saved on

compared with

New Version Current

changes.mady.by.user David Enyeart

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

The content is being published at https://toc.hyperledger.org/ and follow-on targeted task forces may be proposed. , see Pull Request https://github.com/hyperledger/toc/pull/111

...


Proposed project best practices (with links to existing content, related task forces, etc)


Maintainers guidelines includes guidance and examples around:

  • MAINTAINERS.md with 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 filesNo executable binaries


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

    • aries-rfcs
    • Use Community Specification License v1.0 in RFC repositories - Hart to ask LF legal about next steps
  • Maintainer governance - see maintainer guidelines above
  • Document project roles and responsibilities (maintainers, release managers, contributors, etc)
  • Document project operational procedures (including road mapping, retirements)
  • TODO - Task force for defining template project roles, responsibilities, operations (see AnonCreds example - spec repo with Community Specification License, Governance)


Community

  • First and foremost, foster a welcoming, positive, and public environment where contributions are encouraged - see YouTube presentation
  • Decisions should be made in public, or at least socialized in public

  • Mailing lists - start with a single mailing list, consider multiple if there becomes a need (users versus contributors/maintainers)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, link to Discord task force output

  • Public meetings - on a regular cadence. Ask community about best meeting time, consider two meetings to cover different regions, or rotating meeting times (shifted 8 hours or 12 hours)

  • Finding new contributors and users


    Security - add link to security see also 2022 security task force

    • Named Provide named security contacts per project (at least two contacts)

    • Security Define security issue reporting process defined in SECURITY.md with reference to Hyperledger reporting process

    • Review, respond, and act on reported security vulnerabilities

    • Follow security Security issue disclosure process - see task force https://github.com/hyperledger/toc/issues/48 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 (depends on language) Govulncheck 

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

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

    • Engage with Hyperledger staff on possibility of security 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 - proposed task force - https://github.com/hyperledger/toc/issues/49


    Documentation - add link to see Documentation task force and Onboarding task forcesforce

    • Documentation should minimally target these audiences

      • User guide including Getting Started / Tutorial

      Developer

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

      • Application developer guide

    • Documentation task force will address Common styling guide, Recommended documentation platform?common publishing platform, Document best practices for creating documentation, etc.


    Project management

    • Maintain a written project roadmap, discuss in project meetings
    • Create, clarify, and label issues in Github for contributors. Use Github default labels, e.g. "good first issue"
      • Consider splitting "good first issue" label into multiple labels, e.g. "good-first-issue-100-introductory" through "good-first-issue-400-expert" (see Cacti project)
    • Review, triage, comment on, and close inbound Github issues


    Releases

    • Follow an established Release taxonomy - either SemVer or CalVer; use consistent pre-release tags (e.g. -preview, -alpha, -beta)

    • Document release strategy , and release process including required approvals

    • Document branch strategy, branch strategye.g. one branch per major.minor release works well so that it can be maintained in isolation while delivering 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 Actions to automate release process, e.g. publish artifacts and release notes upon drafting a GitHub release
    • Use Reproducible builds
    • Sign release commits with GPG (-S or --gpg-sign); sign release artifacts - see Security Artifact Signing task force

    • Release artifacts

      • binaries

      Release artifacts -

      • attached to GitHub release

      ,

      • docker images

      in GitHub Packages versus Dockerhub

    CI


    Continuous Integration (CI)

    • GitHub Actions is the recommended CI platform, although use efficiently due to limits on number of runners, some ideas to limit runner usage:

      • We are doing trials with BuildJet and faster GitHub runners (will report back)
      • Use cancel-in-progress to suppress multiple jobs for multiple pushes to the same pull request
      • Uncheck branch protection rule "Require branches to be up to date before merging" to reduce number of runs (potentially add a scheduled run if you are concerned about incompatible PRs getting merged)
      • Use filters to eliminate unnecessary runs, e.g. doc PRs shouldn't require building and testing code.
      • Consider running some jobs on schedule (nightly) rather than on each pull request (e.g. full matrix of platform tests)
      • Inspect Github Actions run results on your own fork prior to opening Pull Request
      GitHub Actions recommended

    • Pull request checks

      • DCO - Developer Certificate of Origin

      • Unit tests

      • Integration tests

      • Scans - see Security section, more comprehensive scans can be run nightly insteadconsider running on schedule (nightly) rather than on each pull request
      • Be wary - just because a change passes checks doesn't mean it is necessarily good, it still requires judicious maintainer review

    • Test coverage reporting - run on-demand or nightly

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

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



    GitHub suggestionsconfiguration

    • Define repository settings in Use .github/settings.yml so that repository settings they 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)

    • , see Fabric example.

    • Define Branch protection rules (TODO - define best starting config)

    • Consider using a CODEOWNERS file to specify write permission per directory, see Fabric example with additional /docs maintainers.
      • Add a link to maintainers.md scope field so that users can find domain area contacts
    • Consider using a .github/PULL_REQUEST_TEMPLATE.md and .github/ISSUE_TEMPLATE


    GitHub workflow

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

    • Rebase merging is preferred over Merge commits and Squash merging to keep commit history and PR description clean (assuming contributors squash/amend their own pull requests)
    • Preserve commit hash - rebase then merge with fast forward option
      • git rebase (branch); git merge --ff-only
      • git commit -s versus git commit -S
        • -S is crypto verified, -s is DCO signoff. Rebase preserves both.
    • amend commits to avoid having multiple commits (git commit --amend). If you do have multiple commits squash them before opening PR. Keep pull requests focused to a logical unit of work.
    • Mergify Examples - amending commits versus squashing commits, Mergifyio to simplify cherry picks and backports .- @Mergifyio backport <branch>
    • Example Fabric guidance doc for forking, branching, remotes, creating pull requests, updating pull requests, cherry picking