...

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/ , see Pull Request https://github.com/hyperledger/toc/pull/111

...

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

...

• 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 meetup@hyperledger.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

• Pull Requests

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

  • 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

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

...

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

• Define repository settings in .github/settings.yml so that they can be managed and tracked via pull requests, see Fabric example.

• Define 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?TODO - define best starting config)

  • Add screenshot
  • Reusable github actions
• 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
  • 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 - https://hyperledger-fabric.readthedocs.io/en/latest/github/github.html