# Contribution Guide dble is a community driven open source project and we welcome any contributor.This guide documents the best way to make various types of contribution to dble, including what is required before submitting a code change. Of course, contributing doesn't just mean writing code. Improving documentation and reporting bugs are also welcome. ## Contributing Bug Reports Ideally, bug reports are accompanied by a proposed code change to fix the bug. This isn’t always possible, as those who discover a bug may not have the experience to fix it. A bug may be reported but without creating a pull request (see below). Bug reports are only useful however if they include enough information to understand, isolate and ideally reproduce the bug.Unreproducible bugs, or simple error reports, may be closed. It is possible to propose new features as well. These are generally not helpful unless accompanied by detail, such as a design document and/or code change. Feature requests may be rejected, or closed after a long period of inactivity. ## Contributing Documentation Changes To propose a change to documentation, similarly, edit the Markdown file in the repository and open a pull request. ## Contributing Code Changes This part outlines some conventions about development workflow, commit message formatting, contact points and other resources to make it easier to get your contribution accepted. ## Preparing to Contribute Code Changes ### Choosing What to Contribute Before you move on, please make sure what your issue and/or pull request is, a bug fix or an architecture change. You know that review can take hours or days of committer time, so everyone benefits if contributors focus on changes that are useful, clear, easy to evaluate, and already pass basic checks. Besides all above, each issue should be filed with template. ### Is this a bug fix? Bug fixes usually come with tests. With the help of continuous integration test, patches can be easy to review. Please update the unit tests so that they catch the bug! IMPORTANT:Issue example will be comming soon. ### Is this an architecture improvement? Some examples of "Architecture" improvements: - Improving test coverage. - Decoupling logic or creation of new utilities. - Making code more resilient (sleeps, back offs, reducing flakiness, etc). - Improving performance. If you are improving the quality of code, then justify/state exactly what you are 'cleaning up' in your Pull Request so as to save reviewers' time. IMPORTANT: An example will be comming soon. If you're making code more resilient, test it locally to demonstrate how exactly your patch changes things. ### Workflow ### Step 1: Fork in the cloud 1. Visit https://github.com/actiontech/dble 2. Click `Fork` button (top right) to establish a cloud-based fork. ### Step 2: Clone fork to local storage Create your clone: ``` mkdir -p $working_dir cd $working_dir git clone git@github.com:$user/dble.git # the following is recommended # or: git clone https://github.com/$user/dble.git cd $working_dir/dble git remote add upstream git@github.com:actiontech/dble.git # or:git remote add upstream https://github.com/actiontech/dble.git # Never push to upstream master since you do not have write access git remote set-url --push upstream no_push # Confirm that your remotes make sense: # It should look like: # origin git@github.com:$(user)/dble.git (fetch) # origin git@github.com:$(user)/dble.git (push) # upstream https://github.com/actiontech/dble (fetch) # upstream no_push (push) git remote -v ``` ### Step 3: Branch Get your local master up to date: ```sh cd $working_dir/dble git fetch upstream git checkout master git rebase upstream/master ``` Branch from master: ```sh git checkout -b yours-issue ``` Then edit code on the `yours-issue` branch. #### Compile, Check, Test ```sh # Complie and run unit test to make sure all test passed mvn clean install package ``` ### Step 4: Keep your branch in sync ```sh # While on your yours-issue branch git fetch upstream git rebase upstream/master ``` ### Step 5: CheckCodeStyle see [developer Notice](./DeveloperNotice.md) ### Step 6: Commit Commit your changes. ```sh git commit ``` Likely you'll go back and edit/build/test some more than `commit --amend` in a few cycles. ### Step 7: Push When ready to review (or just to establish an off-site backup or your work), push your branch to your fork on `github.com`: ```sh git push -f origin yours-issue ``` ### Step 8: Create a pull request 1. Visit your fork at https://github.com/$user/dble (replace `$user` obviously). 2. Click the `Compare & pull request` button next to your `yours-issue` branch. #### Step 9: get a code review Once your pull request has been opened, it will be assigned to at least one reviewers. Those reviewers will do a thorough code review, looking for correctness, bugs, opportunities for improvement, documentation and comments, and style. Commit changes made in response to review comments to the same branch on your fork. Very small PRs are easy to review. Very large PRs are very difficult to review. ## Commit message style Please follow this style to make dble easy to review, maintain and develop. ```