Contributing
Contributions are welcome and are greatly appreciated! Every little bit helps, and credit will always be given.
Table of Contents
Types of Contributions
Report Bug
The best way to report a bug is to file an issue on GitHub. Please include:
Your operating system name and version.
Dingo database version.
Detailed steps to reproduce the bug.
Any details about your local setup that might be helpful in troubleshooting.
Submit Ideas or Feature Requests
The best way is to file an issue on GitHub:
Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome :)
For large features or major changes to codebase, please create DingoDB Improvement Proposal (DIP). See template from DIP-0
Fix Bugs
Look through the GitHub issues. Issues tagged with #bug
are
open to whoever wants to implement them.
Implement Features
Look through the GitHub issues. Issues tagged with
#feature
is open to whoever wants to implement it.
Improve Documentation
DingoDB could always use better documentation, whether as part of the official docs or even on the web as blog posts or articles. See Documentation for more details.
Ask Questions
There is a dedicated on Slack or Mailing list. Please use it when asking questions.
Pull Request Guidelines
A philosophy we would like to strongly encourage is
Before creating a PR, create an issue.
The purpose is to separate problem from possible solutions.
Bug fixes: If you’re only fixing a small bug, it’s fine to submit a pull request right away but we highly recommend to file an issue detailing what you’re fixing. This is helpful in case we don’t accept that specific fix but want to keep track of the issue. Please keep in mind that the project maintainers reserve the rights to accept or reject incoming PRs, so it is better to separate the issue and the code to fix it from each other. In some cases, project maintainers may request you to create a separate issue from PR before proceeding.
Refactor: For small refactors, it can be a standalone PR itself detailing what you are refactoring and why. If there are concerns, project maintainers may request you to create a #DIP
for the PR before proceeding.
Feature/Large changes: If you intend to change the public API, or make any non-trivial changes to the implementation, we require you to file a new issue as #DIP
(DingoDB Improvement Proposal). This lets us reach an agreement on your proposal before you put significant effort into it. You are welcome to submit a PR along with the DIP (sometimes necessary for demonstration), but we will not review/merge the code until the DIP is approved.
In general, small PRs are always easier to review than large PRs. The best practice is to break your work into smaller independent PRs and refer to the same issue. This will greatly reduce turnaround time.
If you wish to share your work which is not ready to merge yet, create a Draft PR. This will enable maintainers and the CI runner to prioritize mature PR’s.
Finally, never submit a PR that will put master branch in broken state. If the PR is part of multiple PRs to complete a large feature and cannot work on its own, you can create a feature branch and merge all related PRs into the feature branch before creating a PR from feature branch to master.
Protocol
Reviewing
Use constructive tone when writing reviews.
If there are changes required, state clearly what needs to be done before the PR can be approved.
If you are asked to update your pull request with some changes there’s no need to create a new one. Push your changes to the same branch.
The committers reserve the right to reject any PR and in some cases may request the author to file an issue.
Merging
At least one approval is required for merging a PR.
PR is usually left open for at least 24 hours before merging.
After the PR is merged, close the corresponding issue(s).
Post-merge Responsibility
Project maintainers may contact the PR author if new issues are introduced by the PR.
Project maintainers may revert your changes if a critical issue is found, such as breaking master branch CI.
Managing Issues and PRs
To handle issues and PRs that are coming in, committers read issues/PRs and flag them with labels to categorize and help contributors spot where to take actions, as contributors usually have different expertises.
Triaging goals
For issues: Categorize, screen issues, flag required actions from authors.
For PRs: Categorize, flag required actions from authors. If PR is ready for review, flag required actions from reviewers.
First, add Category labels (a.k.a. hash labels). Every issue/PR must have one hash label (except spam entry). Labels that begin with #
defines issue/PR type:
Label |
for Issue |
for PR |
---|---|---|
|
Bug report |
Bug fix |
|
Describe problem with code, architecture or productivity |
Refactor, tests, tooling |
|
New feature request |
New feature implementation |
|
Propose improvement that does not provide new features and is also not a bug fix nor refactor, such as adjust padding, refine UI style. |
Implementation of improvement that does not provide new features and is also not a bug fix nor refactor, such as adjust padding, refine UI style. |
|
Documentation |
Documentation |
|
Troubleshooting: Installation, Running locally, Ask how to do something. Can be changed to |
N/A |
|
DingoDB Improvement Proposal |
N/A |
Then add other types of labels as appropriate.
Need labels: These labels have pattern
need:xxx
, which describe the work required to progress, such asneed:rebase
,need:update
,need:screenshot
.Risk labels: These labels have pattern
risk:xxx
, which describe the potential risk on adopting the work, such asrisk:db-migration
. The intention was to better understand the impact and create awareness for PRs that need more rigorous testing.Status labels: These labels describe the status (
abandoned
,wontfix
,cant-reproduce
, etc.) Issue/PRs that are rejected or closed without completion should have one or more status labels.Version labels: These have the pattern
vx.x
such asv0.28
. Version labels on issues describe the version the bug was reported on. Version labels on PR describe the first release that will include the PR.
Committers may also update title to reflect the issue/PR content if the author-provided title is not descriptive enough.
If the PR passes CI tests and does not have any need:
labels, it is ready for review, add label review
and/or design-review
.
If an issue/PR has been inactive for >=30 days, it will be closed. If it does not have any status label, add inactive
.
Setup Local Environment for Development
First, fork the repository on GitHub, then clone it. You can clone the main repository directly, but you won’t be able to send pull requests.
git clone git@github.com:your-username/dingo.git
cd dingo
./gradlew build
Documentation
The latest documentation and tutorial are available at https://dingodb.io/.