Hedera Hashgraph is grateful for any contributions it receives from the community. Contributions can come in many shapes and forms including bug reports, code, answering questions on Discord, etc. This document outlines the process to help get your contribution accepted.
If you have a question on how to use the product, please see our Support guide.
GitHub issues are used as the primary method for tracking project changes. Issues should track actionable items that will result in changes to the codebase. As a result, support inquiries should be directed to one of the aforementioned support channels.
Most of the time, when you find a bug, it should be reported the GitHub issue tracker for the project. However, if you are reporting a security vulnerability, please see our Hedera bug bounty program.
There are three types of issues each with their own corresponding label:
- Bug: These track issues with the code
- Documentation: These track problems or insufficient coverage with the documentation
- Enhancement: These track specific feature requests and ideas until they are complete. This should only be for trivial or minor enhancements. If the feature is sufficiently large, complex or requires coordination among multiple Hedera projects, it should first go through the Hedera Improvement Proposal process.
The issue lifecycle is mainly driven by the core maintainers, but is still useful to know for those wanting to contribute. All issue types follow the same general lifecycle. Differences will be noted below.
- The user will open a ticket in the GitHub project and apply one of the issue type labels.
- The maintainer in charge of triaging will apply the proper labels for the issue. This includes labels for priority and area.
- Clean up the title to succinctly and clearly state the issue (if needed).
- Ask the submitter to clarify any items.
- We attempt to do this process at least once per work day.
- Issues should be connected to the pull request that resolves it.
- Whoever is working on an issue (whether a maintainer or someone from the community), should either assign the issue to themself or add a comment that they will be working on it.
- Linked issues should be automatically closed when a PR is merged or closed manually by the submitter or maintainer if it is determined that is not necessary.
Like most open source projects, we use pull requests ( PRs) to track code changes.
-
Fork the repository. Go to the project page then hit the
Forkbutton to fork your own copy of the repository to your GitHub account. -
Clone the forked repository to your local working directory.
$ git clone https://github.com/${owner}/${repo}.git- Add an
upstreamremote to keep your fork in sync with the main repo.
$ git remote add upstream https://github.com/hashgraph/${repo}.git- Sync your local
mainbranch.
$ git pull upstream mainNote Some repositories may still be using
masterfor their default branch.
- Create a branch to add a new feature or fix issues.
$ git checkout -b new-feature-
Make any change on the branch
new-featurethen build and test your code locally. -
Add files that you want to be committed.
$ git add <file>- Enable GPG signing of your commits within the repo. Signing all your commits with your public key allows the comunity to verify it's really you. If you forgot to sign some commits that are part of the contribution, you can ask git to rewrite your commit history.
$ git config commit.gpgsign true- Use sign-off when making each of your commits. Additionally, please GPG sign all your commits with your public key so we can verify it's really you. If you forgot to sign-off some commits that are part of the contribution, you can ask git to rewrite your commit history.
$ git commit --signoff -S -m "Your commit message"- Submit a pull request.
The sign-off is a simple line at the end of a commit message. All commits needs to be signed. Your signature certifies that you wrote the code or otherwise have the right to contribute the material. First, read the Developer Certificate of Origin (DCO) to fully understand its terms.
Contributors sign-off that they adhere to these requirements by adding a Signed-off-by line to commit messages (as
seen via git log):
Author: Joe Smith <[email protected]>
Date: Thu Feb 2 11:41:15 2018 -0800
Update README
Signed-off-by: Joe Smith <[email protected]>
Use your real name and email (sorry, no pseudonyms or anonymous contributions). Notice the Author and Signed-off-by
lines match. If they don't your PR will be rejected by the automated DCO check.
If you set your user.name and user.email git configs, you can sign your commit automatically with -s
or --sign-off command line option:
$ git config --global user.name "Joe Smith"
$ git config --global user.email "[email protected]"
$ git commit -s -m 'Update README'Now that you've got your forked branch, you can proceed to submit it.
- It is preferred, but not required, to have a PR tied to a specific issue. There can be circumstances where if it is a quick fix then an issue might be overkill. The details provided in the PR description would suffice in this case.
- The PR description or commit message should contain a keyword to automatically close the related issue.
- Commits should be as small as possible, while ensuring that each commit is correct independently (i.e., each commit should compile and pass tests).
- Add tests and documentation relevant to the fixed bug or new feature. Code coverage should stay the same or increase for the PR to be approved.
- We more than welcome PRs that are currently in progress. If a PR is a work in progress, it should be opened as a Draft PR. Once the PR is ready for review, mark it as ready to convert it to a regular PR.
- After submitting, ensure all GitHub checks pass before requesting a review. Also double-check all static analysis and coverage tools show a sufficient coverage and quality level.
- The maintainer in charge of triaging will apply the proper labels for the PR.
- Add the PR to the correct milestone. This should be the same as the issue the PR closes.
- The maintainer can assign a reviewer, or a reviewer can assign themselves.
- All reviews will be completed using the GitHub review tool.
- A "Comment" review should be used when there are questions about the code that should be answered, but that don't involve code changes. This type of review does not count as approval.
- A "Changes Requested" review indicates that changes to the code need to be made before they will be merged.
- For documentation, special attention will be paid to spelling, grammar, and clarity (whereas those things don't matter as much for comments in code).
- Reviews are also welcome from others in the community. In the code review, a message can be added, as well as
LGTMif the PR is good to merge. It’s also possible to add comments to specific lines in a file, for giving context to the comment. - PR owner should try to be responsive to comments by answering questions or changing code. If the owner is unsure of any comment, please ask for clarification in the PR comments.
- Once all comments have been addressed and all reviewers have approved, the PR is ready to be merged.
- PRs should stay open until they are merged or closed. The issue may be closed if the submitter has not been responsive for more than 30 days. This will help keep the PR queue to a manageable size and reduce noise.
Hedera uses Semantic Versioning for releases to convey meaning about the underlying code and what has been modified from one version to the next. We use milestones to track the progress of a release. Assigning issues to a milestone is on a best effort basis, and we make no guarantees as to when a particular issue will be released. A milestone (and hence release) is considered done when all outstanding issues and PRs have been closed or moved to another milestone.