[Couchdb Wiki] Update of "ContributorWorkflow" by DaveCottlehuber

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Couchdb Wiki" for change notification.

The "ContributorWorkflow" page has been changed by DaveCottlehuber:
http://wiki.apache.org/couchdb/ContributorWorkflow?action=diff&rev1=15&rev2=16

Comment:
partial clean up after reading the mishmash -- needs work on the final push origin section, assuming that non-committers will use a github repo.

  
  === Git Workflow ===
  
- Consider that you've decided to work on ticket #11 for the CouchDB repository. You are charged with updating some text file.
+ Consider that you've decided to work on JIRA ticket #123 for the CouchDB repository. You are charged with updating a INI file.
  
  ==== Update your master branch ====
  
- We're assuming you have cloned the CouchDB repository as per the example above, and have the docs repository set up as a "couchdb" remote, with your own fork as the "origin". Let's first make sure your fork is up-to-date, by retrieving new commits from the canonical ASF repo (origin) and then merging them as a fast-forward into our repo.
+ We're assuming you have cloned the CouchDB repository as per the example above. Let's first make sure your fork is up-to-date, by retrieving new commits from the canonical ASF repo (origin) and then merging them as a fast-forward into your local branch.
  
  {{{
+ # switch to our own local master branch
  $ git checkout master
+ # retrieve all new commits from the remote origin, into our local git repo
  $ git fetch origin
+ # merge those new commits into the local master branch only if there is a direct and linear commit path
  $ git merge --ff-only origin/master
  }}}
  
  If the merge fails, then your master branch has diverged from the ASF one. Normally this is not desirable as when you push patches back they may not be able to be applied cleanly.
  
- {{{
- $ git push origin master
- }}}
- 
  ==== Create a topic branch ====
  
- Let's create a new branch based off of master and call it "ticket_11".
  
+ Topic branches should be named {{{<jira-ticket>-[fix|feature]-<short-description>}}}. For example, {{{1368-fix-multipart-header-parts}}} refers to [[https://issues.apache.org/jira/browse/COUCHDB-1368|COUCHDB-1368]] in JIRA, and is a {{{fix}}} for the {{{multipart-header-parts}}} issue.
+ 
+ We've been asked to fix an INI file, referred to in fictional JIRA ticket 123. So let's create a new branch based off of master and call it "123-fix-ini-file"
+ 
  {{{
  $ git checkout master
- $ git checkout -b ticket_11
+ # make a new branch that is up to date with the ASF repo master branch.
+ $ git checkout -b 123-fix-ini-file
  $ git branch
    master
- * ticket_11
+ * 123-fix-ini-file
  }}}
  
- You can name the topic branch anything, but it makes sense to name it after the ticket. This topic branch is now isolated and branched off the history of your master branch.
+ This topic branch is now isolated and branched off the history of your master branch, which also matches the current master branch in ASF. Everybody's cool with this.
  
  ==== Make File Changes ====
  
- Let's update the accelerometer documentation for the "watchPosition" function.
+ Let's update the textfile:
  
  {{{
  $ [ edit etc/couchdb/default.ini.tpl.in ]
@@ -117, +120 @@

  
  ==== Prepare to Send Pull Request ====
  
- Before sending the pull request, you should ensure that your changes merge cleanly with the main documentation repository.
+ Before sending the pull request, you should ensure that your changes merge cleanly with the main repository. You can do this by pulling the latest changes from the main repository back into our master. We make sure that our master is always in sync before issuing pull requests:
  
  {{{
  $ git checkout master
- $ git pull couchdb master
+ $ git pull origin master
- $ git checkout ticket_11
+ $ git checkout 123-fix-ini-file
  $ git rebase master
  }}}
  
- You can do this by pulling the latest changes from the main repository back into our master. We make sure that our master is always in sync before issuing pull requests. Next, we rebase the history of the master branch onto the topic branch ticket_11. Essentially, this will rewind your divergent commits, fast-forward your topic branch to the latest commit of the master, and then re-apply your topic branch commits in order. Ensures a clean application of code changes. The [[http://book.git-scm.com/4_rebasing.html|git community book has an excellent chapter on rebasing]].
+ This approach will pop off any of your commits that are *not* on the ASF master branch, subsequently apply the missing commits from master to bring you up to date, and then finally push your commits back on, in the same order, to make things clean and tidy. This results in a nice clear linear history on the public repos. The [[http://book.git-scm.com/4_rebasing.html|git community book has an excellent chapter on rebasing]].
  
- Alternatively, you can use git merge master instead of git rebase master, but your topic branches history may not be as clean.
+ Merge to master should be done in consultation with our git gurus. You know who they are!
  
- Last thing is to make your code changes available from your fork.
+ Last thing is to make your code changes available from your fork, and push them up to either the ASF repo (if you are a committer), or to your own repo (e.g. on github) if you are not a committer.
  
  {{{
- $ git checkout ticket_11
- $ git push origin ticket_11
+ $ git checkout 123-fix-ini-file
+ $ git push origin 123-fix-ini-file
  }}}
  
  ==== Sharing your Changes ====
@@ -166, +169 @@

  $ git branch -a
  * document_blahfasel_setting
    master
-   ticket_11
+   123-fix-ini-file
  }}}
  
  === When Your Pull Request is Accepted ===
@@ -181, +184 @@

  You can now delete your topic branch, because it is now merged into the main repository and in the master branch.
  
  {{{
- $ git branch -d ticket_11
- $ git push origin :ticket_11
+ $ git branch -d 123-fix-ini-file
+ $ git push origin :123-fix-ini-file
  }}}
  
- I know, deleting a remote topic branch is ugly (git push origin :ticket_11).
+ I know, deleting a remote topic branch is ugly (git push origin :123-fix-ini-file).
  
  === If Your Pull Request is Rejected ===
  
@@ -194, +197 @@

  {{{
  $ git checkout master
  $ git pull origin master
- $ git checkout ticket_11
+ $ git checkout 123-fix-ini-file
  $ git rebase master
  ( edit / commit / edit / commit)
- $ git push origin ticket_11
+ $ git push origin 123-fix-ini-file
  }}}