tamaya-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ple...@apache.org
Subject [1/3] incubator-tamaya git commit: TAMAYA-95 Added the Git workflow suggestions from the curent website to the development guidelines.
Date Sun, 06 Sep 2015 22:05:53 GMT
Repository: incubator-tamaya
Updated Branches:
  refs/heads/master b81fbc1bd -> f71c44601


TAMAYA-95 Added the Git workflow suggestions from the curent website to the development guidelines.


Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/commit/677c7b0b
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/tree/677c7b0b
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/diff/677c7b0b

Branch: refs/heads/master
Commit: 677c7b0bbed440ca608484bce5244556167dab03
Parents: 4ec4518
Author: Oliver B. Fischer <plexus@apache.org>
Authored: Sun Sep 6 12:52:31 2015 +0200
Committer: Oliver B. Fischer <plexus@apache.org>
Committed: Sun Sep 6 12:53:16 2015 +0200

----------------------------------------------------------------------
 src/site/asciidoc/devguide/index.adoc | 207 +++++++++++++++++++++++++++++
 src/site/site.xml                     |   1 +
 2 files changed, 208 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/677c7b0b/src/site/asciidoc/devguide/index.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/devguide/index.adoc b/src/site/asciidoc/devguide/index.adoc
new file mode 100644
index 0000000..0fce0c9
--- /dev/null
+++ b/src/site/asciidoc/devguide/index.adoc
@@ -0,0 +1,207 @@
+= Apache Tamaya -- Development Guide
+//:name: Tamaya
+//:rootpackage: org.apache.tamaya
+//:title: Apache Tamaya
+//:revnumber: 0.1-SNAPSHOT
+//:revremark: Incubator
+//:revdate: November 2014
+//:longversion: {revnumber} ({revremark}) {revdate}
+//:authorinitials: ATR
+//:author: Anatole Tresch
+//:email: <anatole@apache.org>
+:source-highlighter: coderay
+//:website: http://tamaya.incubator.apache.org/
+:toc:
+//:toc-placement: manual
+:encoding: UTF-8
+:numbered:
+
+
+== 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://git-wip-us.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
+----
+
+
+== 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://git-wip-us.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
+----

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/677c7b0b/src/site/site.xml
----------------------------------------------------------------------
diff --git a/src/site/site.xml b/src/site/site.xml
index 8da24c2..f84587e 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -40,6 +40,7 @@ under the License.
 
         <menu name="Documentation">
             <item name="Release Guide" href="release-guide.html"/>
+            <item name="Development Guide" href="devguide/"/>
         </menu>
 
         <menu name="JavaDoc">


Mime
View raw message