| :jbake-type: page |
| :jbake-status: published |
| |
| :sectnums: yes |
| |
| = Apache Tamaya: Development Guide |
| |
| == Suggested Git Workflows |
| |
| === Avoid git pull! |
| |
| `git pull` should never get invoked if you have dirty files lying around |
| or if your branch is ahead of master. This will always lead to |
| some dirty artifacts in the commit history: |
| |
| ---- |
| Merge branch 'master' of http://gitbox.apache.org/tamaya into master |
| ---- |
| |
| === Use git pull --rebase |
| |
| An easy version for getting rid of the auto-merges is using |
| |
| ---- |
| $ git pull --rebase |
| ---- |
| |
| Please note that this sometimes trashes your working tree if there |
| are unmergeable files around. Cleaning this up with a forced manual |
| rebase is not something we would recommend for a git beginner. |
| |
| === Working in an own branch |
| |
| This is actually the suggested way to prevent auto-merges. Create an own |
| branch where you do your feature work. Either do all your work in one |
| branch or create one branch per feature you are working on. |
| |
| ---- |
| $ git branch mybranch |
| ---- |
| |
| After you finished your feature, first add (`git add`) and commit (`git commit`) your work. |
| Check with `git status` that you don't have any dirty files and uncommitted |
| changes around. You can use `git stash` to 'backup' unfinished work. |
| |
| Then switch back to the master branch and pull changes |
| done by other committers in the meantime. |
| |
| ---- |
| $ git checkout master |
| $ git pull --rebase |
| ---- |
| |
| You should now get all the changes done by other committers and |
| the will get applied to your local master branch. Now go back to |
| your private branch and rebase your locally performed work to the HEAD of master. |
| |
| ---- |
| $ git checkout mybranch |
| $ git rebase master |
| ---- |
| |
| If you got conflicts, you will get lines with ">>>>" added to those |
| files. Resolve those conflicts manually, add them and finish the rebase. |
| |
| Check with `git-status` and `gitk` if the merge went well and the history now contains your changes. |
| If all is well, go back to the master branch and merge your changes in. |
| |
| ---- |
| $ git pull --rebase // (just for safety, you should see no changes) |
| $ git checkout master |
| $ git merge mybranch |
| ---- |
| |
| Finally you can push your changes to the ASF git repo |
| |
| ---- |
| $ git push |
| ---- |
| |
| [[contributing-workflow]] |
| == Contribution workflow |
| |
| === Creating patches |
| |
| You should use the following workflow, if you plan to contribute |
| patches or new features to Tamaya. |
| |
| First update you local copy of the repository: |
| |
| ---- |
| $ git checkout master |
| $ git pull --rebase |
| ---- |
| |
| Then create a new local branch for your work. It's good practice to name |
| it after the corresponding JIRA issue. |
| |
| ---- |
| $ git checkout -b TAMAYA-XXX |
| ---- |
| |
| Now you can start to work on your patch. When you are finished, commit your changes. But don't forget to **add the name |
| of the JIRA issue to the commit message**. |
| |
| ---- |
| $ git add -am "TAMAYA-XXX: Fixed some issue" |
| ---- |
| |
| For small patches we recommend to do a single commit containing your changes. For larger contributions you should try |
| to group your work into separate sub-tasks that you can commit one by one. |
| |
| Before you create your patch you should make sure that your local repository is up to date with the master repository. |
| This is very important especially if you work on your branch for a long time. Use the following commands to pull the |
| latest changes from the upstream repository and rebase your branch against the current master. |
| |
| |
| ---- |
| $ git checkout master |
| $ git pull --rebase |
| $ git checkout TAMAYA-XXX |
| $ git rebase master |
| ---- |
| |
| Now you are ready to create your patch: |
| |
| ---- |
| $ git checkout TAMAYA-XXX |
| $ git format-patch --stdout master > ../TAMAYA-XXX.patch |
| ---- |
| |
| Please attach the resulting patch file to the correspoding JIRA issue. |
| |
| === Applying patches |
| |
| If you are a committer and want to apply a patch you should do so in a separate branch. |
| |
| ---- |
| $ git checkout -b TAMAYA-XXX |
| ---- |
| |
| Then apply the patch using `git am` and rebase it against the master branch. |
| |
| ---- |
| $ git am < ../TAMAYA-XXX.patch |
| $ git rebase master |
| ---- |
| |
| After reviewing the changes and testing the code, the changes are ready to |
| be merged into the master branch: |
| |
| ---- |
| $ git checkout master |
| $ git merge TAMAYA-XXX |
| $ git branch -d TAMAYA-XXX |
| ---- |
| |
| === Discussion workflow (optional) |
| |
| All discussions which lead to a decision take place on the mailing list. |
| Sometimes it's required to show-case an idea esp. if the solution is |
| more than few lines. As shown above it makes sense to use local branches |
| for developing new parts. Git allows to push such local branches to a |
| public repository. So it's easier to share it with the community |
| for discussing it. The following listings show an example in combination |
| with GitHub - for sure it works with any hosting platform like BitBucket, |
| Google-Code,... The only important part here is that such branches |
| *NEVER* get pushed to the main Apache repository to keep the commit history |
| as clean as possible. |
| |
| === Initial setup |
| |
| ---- |
| $ git clone https://gitbox.apache.org/repos/asf/incubator-tamaya.git |
| $ git remote add discuss https://[username]@github.com/[username]/[repo-name].git |
| $ git push -u discuss master |
| ---- |
| |
| === Branches for discussions |
| |
| ---- |
| $ git checkout -b TAMAYA-XXX # 1-n commits |
| $ git push discuss TAMAYA-XXX # share the link to the branch for the discussions |
| ---- |
| |
| *If the community agrees on the suggested change, the implementation will be applied to the origin master. A committer |
| has to follow the steps described above for the basic workflow to keep the commit history simple, clean and straight. |
| A contributor has to follow the steps described above for creating a patch.* |
| |
| === Delete the branch again |
| |
| ---- |
| $ git push discuss :TAMAYA-XXX |
| $ git branch -d TAMAYA-XXX |
| ---- |