couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Couchdb Wiki] Update of "ContributorWorkflow" by DaveCottlehuber
Date Sat, 24 Nov 2012 14:57:15 GMT
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
  }}}
  

Mime
View raw message