...
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)
...
Define repository settings in .github/settings.yml so that they can be managed and tracked via pull requests, see Fabric example.
- Use recommended repository settings as a starting point, e.g. Repository options,
Define Branch protection rules (TODO - define best starting config)
- Add screenshot
- Reusable github actionsTBD by TOC and Hyperledger staff)
- 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
- 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)
- 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.
- 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
amend commits instead of squashing commits - "git commit --amend"
Mergifyio to simplify cherry picks and backports - "- 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
@Mergifyio backport <branch>
"