You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltaspike.apache.org by gp...@apache.org on 2012/11/13 01:24:13 UTC
svn commit: r1408516 -
/incubator/deltaspike/site/trunk/content/deltaspike/suggested-git-workflows.mdtext
Author: gpetracek
Date: Tue Nov 13 00:24:12 2012
New Revision: 1408516
URL: http://svn.apache.org/viewvc?rev=1408516&view=rev
Log:
updated content
Modified:
incubator/deltaspike/site/trunk/content/deltaspike/suggested-git-workflows.mdtext
Modified: incubator/deltaspike/site/trunk/content/deltaspike/suggested-git-workflows.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/suggested-git-workflows.mdtext?rev=1408516&r1=1408515&r2=1408516&view=diff
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/suggested-git-workflows.mdtext (original)
+++ incubator/deltaspike/site/trunk/content/deltaspike/suggested-git-workflows.mdtext Tue Nov 13 00:24:12 2012
@@ -18,8 +18,6 @@ Notice: Licensed to the Apache Softwa
# Suggested workflows
-Feel free to add suggestions for workflows which lead to a clean history on the central clone. The description should be useful also for beginners to allow an easier start for new committers.
-
## Avoid git-pull!
git-pull should never get invoked if you have dirty files lying around or if your branch is ahead of master.
@@ -33,9 +31,9 @@ An easy version for getting rid of the a
%> git pull --rebase
-Please not that this sometimes trashes your working tree if there are unmergeable files around. Cleaning this up with a forced manual rebase is not something I'd recommend for a git beginner.
+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
+### Working in an own branch
This is actually the suggested way to prevent auto-merges.
@@ -43,7 +41,7 @@ Create an own branch where you do your f
%> git branch mybranch
-After you finished your feature, git-add and 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.
+After you finished your feature, `git-add` and `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.
@@ -58,7 +56,7 @@ Now go back to your private branch and r
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.
+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)
@@ -74,44 +72,34 @@ Finally you can push your changes to the
### Creating patches
-You should use the following workflow if you plan to contribute patches or new features to DeltaSpike.
+You should use the following workflow, if you plan to contribute patches or new features to DeltaSpike.
First update you local copy of the repository:
-{code}
- %> git checkout master
- %> git pull --rebase
-{code}
+ %> 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.
-{code}
- %> git checkout -b DELTASPIKE-XXX
-{code}
-
-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.
-
-{code}
- %> git add -am "DELTASPIKE-XXX: Fixed some issue"
-{code}
+ %> git checkout -b DELTASPIKE-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 "DELTASPIKE-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.
-{code}
- %> git checkout master
- %> git pull --rebase
- %> git checkout DELTASPIKE-XXX
- %> git rebase master
-{code}
+ %> git checkout master
+ %> git pull --rebase
+ %> git checkout DELTASPIKE-XXX
+ %> git rebase master
Now you are ready to create your patch:
-{code}
- %> git checkout DELTASPIKE-XXX
- %> git format-patch --stdout master > ../DELTASPIKE-XXX.patch
-{code}
+ %> git checkout DELTASPIKE-XXX
+ %> git format-patch --stdout master > ../DELTASPIKE-XXX.patch
Please attach the resulting patch file to the correspoding JIRA issue.
@@ -119,45 +107,40 @@ Please attach the resulting patch file t
If you are a committer and want to apply a patch you should do so in a separate branch.
-{code}
- %> git checkout -b DELTASPIKE-XXX
-{code}
-
-Then apply the patch using "git-am" and rebase it against the master branch.
-
-{code}
- %> git am < ../DELTASPIKE-XXX.patch
- %> git rebase master
-{code}
+ %> git checkout -b DELTASPIKE-XXX
+
+Then apply the patch using `git-am` and rebase it against the master branch.
+
+ %> git am < ../DELTASPIKE-XXX.patch
+ %> git rebase master
After reviewing the changes and testing the code, the changes are ready to be merged into the master branch:
-{code}
- %> git checkout master
- %> git merge DELTASPIKE-XXX
- %> git branch -d DELTASPIKE-XXX
-{code}
+ %> git checkout master
+ %> git merge DELTASPIKE-XXX
+ %> git branch -d DELTASPIKE-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.
-{code:title=Initial setup}
- %> git clone https://git-wip-us.apache.org/repos/asf/incubator-deltaspike.git ./
- %> git remote add discuss https://[username]@github.com/[username]/[repo-name].git
- %> git push -u discuss master
-{code}
-
-{code:title=Branches for discussions}
- %> git checkout -b DELTASPIKE-XXX
- //1-n commits
- %> git push discuss DELTASPIKE-XXX
- //share the link to the branch for the discussions
-{code}
+**Initial setup**
+
+ %> git clone https://git-wip-us.apache.org/repos/asf/incubator-deltaspike.git ./
+ %> git remote add discuss https://[username]@github.com/[username]/[repo-name].git
+ %> git push -u discuss master
+
+**Branches for discussions**
+
+ %> git checkout -b DELTASPIKE-XXX
+ //1-n commits
+ %> git push discuss DELTASPIKE-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.*
-{code:title=Delete the branch again}
- %>git push discuss :DELTASPIKE-XXX
- %>git branch -d DELTASPIKE-XXX
-{code}
\ No newline at end of file
+**Delete the branch again**
+
+ %>git push discuss :DELTASPIKE-XXX
+ %>git branch -d DELTASPIKE-XXX
\ No newline at end of file