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.

The content is being published at https://toc.hyperledger.org/ , 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 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 Documentation task force and Onboarding task force

  • Documentation should minimally target these audiences

    • User guide including Getting Started / Tutorial

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

    • Application developer guide

  • Documentation task force will address Common styling guide, Recommended 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


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

  • Pull request checks

    • DCO - Developer Certificate of Origin

    • Unit tests

    • Integration tests

    • Scans - see Security section, consider 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



GitHub configuration

  • Define repository settings in .github/settings.yml so that they can be managed and tracked via 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 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
    • TODO add this to Hyperledger TOC best practices site instead of buried in Fabric docs, add a link to Git-help Discord channel for git/github questions and discussions




  • No labels

13 Comments

  1. Jim Zhang

    very thorough list already David Enyeart

    Under Community, besides public meetings, we can list other channels and resources the foundation provides, and encourage projects to utilize:

    • workshops
    • Hyperledger meetup groups
    • I'm sure there are more venues to help engage with the community


    1. David Enyeart

      Thanks, added above!

  2. Ramakrishna V

    Very comprehensive, David Enyeart !

    On the question of where to publish Docker images, I'd suggest a default recommendation (if not a mandate) to publish them to GitHub packages as that would probably reduce maintenance overhead for users tapped into the GitHub ecosystem. Project maintainers can additionally publish to Dockerhub if they wish (and their client/user pipelines require it).

    I'm not sure what the full scope of this task force is. "Project best practices" could easily encompass everything, including onboarding and documentation, which have their separate task forces. I'm guessing it's the following two things: (1) repository maintenance, and (2) engagement with the community of developers and users. Should development and triage modes also be within the scope of the recommenations? Like how "agile" the development should be, whether there should be scrum (or at least triage) calls, etc.? Or perhaps these should be project-specific (just thinking out loud): how a mature project like, say, Fabric operates may not be appropriate to a newly incubated project.

    Commercial software development teams typically maintain different versions of their projects: minimally two (dev/test and production) and often three (intermediate stage for scalability, security, etc. testing). Should we consider making recommendations for this?

    1. David Enyeart

      Concerning scope, it is indeed meant to be all encompassing. That being said, it is meant to be a very high level view only, with references to other content and other task forces where applicable.

      Some high level operational guidance to projects makes sense, we've added a bullet to consider spawning a task force for that.

      Concerning docker image repository, makes sense to encourage GitHub Packages, although some projects with existing dockerhub images will have to consider how to evolve while minimizing impact to existing users.

      Concerning different versions, this is typically done using release branches (e.g. Fabric has a main branch, release-2.5 branch, etc). We'll discuss in more depth when we get to the Releases section...let me know if I've misunderstood the question though.

      1. Ramakrishna V

        Regarding versions, I agree. The Fabric method of release branches works as a good practice, and I think most mature repos (at least the ones that have active dependencies) follow it, so we should specify that in the guidelines.

        1. David Enyeart

          Added!

  3. Tracy Kuhrt

    Perhaps common "contributing" content can be aggregated so that each project doesn't have to re-invent and re-document.

    I like this. In the documentation task force document template, I copied the Sawtooth one, but there may be good stuff in the other contributing documents that should be included. There are also pages there on reporting a bug, requesting a change, and asking a question.


  4. Tracy Kuhrt

    For the security topic, we might also want to include a link to the presentation that Arnaud did on OpenSSF and the recording to that meeting.

    1. David Enyeart

      Added!

  5. Tracy Kuhrt

    For the documentation section, I have created a documentation template that might be useful. Planning on running this through the documentation task force. Also, the Hyperledger Staff is recommending Material for MkDocs published to GitHub pages as the recommended platform.

    1. David Enyeart

      Cool, I'll await doc task force outputs and link to that.

  6. David Boswell

    David Enyeart – Apologies that I had to drop from the recent TOC call right when the topic of meetups and workshops for the Best Practices TF was being discussed.  I've added some more details about meetups and workshops and information about how maintainers can reach out about setting them up.  I also added a couple other thoughts for maintainers to consider related to finding more contributors and users.

  7. David Boswell

    This is great to see the information getting added here – this is a very thorough guide to support projects and labs.  We had briefly started on something like this a couple of years ago but didn't get very far.  There may be some material there worth reusing though, so feel free to copy anything that seems relevant from the draft Maintainer's Guide.