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
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:
- CI files
License headers on all source 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.
Use an RFC process (or similar process) for driving consensus and tracking agreement on project major decisions, features, design, etc. Examples:
https://github.com/hyperledger/sawtooth-rfcs (same process in Ursa, Grid)
- https://github.com/hyperledger/sawtooth-rfcs/blob/main/text/0006-sawtooth-governance.md (more details on Sawtooth RFC process wrt team structure and decision making)
https://github.com/hyperledger/fabric-rfcs (evolution of Sawtooth RFC process, example of github pages)
- 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)
- 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)
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
- Present at Meetups - Virtual or in person – these are well attended and the videos also get many views
- Email firstname.lastname@example.org if you're interested in presenting or join one of the bi-weekly Meetup and Workshop planning calls every other Thursday at 9:30 AM pacific
- Host technical Workshops - Virtual or in person (e.g. Global Forum) – these are well attended and the videos also get many views
- Reach out to one of the Hyperledger Community Architects or join one of the bi-weekly Meetup and Workshop planning calls every other Thursday at 9:30 AM pacific
- Take part in annual Mentorship program
- Near the beginning of each year maintainers have the option to submit projects to the annual Hyperledger mentorship program and work with mentees or code, documentation or research projects
- Other things to consider
- This doc has other ideas to consider to help you connect with more users and contributors: Raising the Profile of your Hyperledger Project or Lab
- Present at Meetups - Virtual or in person – these are well attended and the videos also get many views
Quick review turnarounds are appreciated and encourage future contributions (and shows up in Insight reports).
Equal attention to PRs - review in order of arrival as a general rule of thumb.
- 'Over'-communicate in PR comments, especially if review is delayed - contributors don't know what is in a maintainer's head
- Be gentle on new contributors, perhaps relax coding guidelines and fix up later
- Don't leave contributors hanging... if the contribution is not a good fit say so
- Mentor new contributors through the process, in PRs and otherwise
Contributing docs - examples:
- NOTE - Perhaps common "contributing" content can be aggregated so that each project doesn't have to re-invent and re-document, or at least a common template.
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:
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?
- Maintain a written project roadmap
- Create, clarify, and label issues in Github for contributors
- Review, triage, comment on, and close Github issues
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
- 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
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.
Examples - amending commits versus squashing commits, Mergifyio to simplify cherry picks and backports.
Example guidance for forking, branching, remotes, creating pull requests, updating pull requests, cherry picking - https://hyperledger-fabric.readthedocs.io/en/latest/github/github.html
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:
Thanks, added above!
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?
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.
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.
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.
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.
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.
Cool, I'll await doc task force outputs and link to that.
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.
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.