Mailing-List: contact commits-help@couchdb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@couchdb.apache.org
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
From: Apache Wiki <wikidiffs@apache.org>
To: Apache Wiki <wikidiffs@apache.org>
Date: Thu, 04 Jun 2015 07:42:24 -0000
Message-ID: <20150604074224.50813.8210@eos.apache.org>
Subject: 
 =?utf-8?q?=5BCouchdb_Wiki=5D_Update_of_=22ContributorWorkflow=22_by_andyw?=
 =?utf-8?q?enk?=
Auto-Submitted: auto-generated

Dear Wiki user,

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

The "ContributorWorkflow" page has been changed by andywenk:
https://wiki.apache.org/couchdb/ContributorWorkflow?action=3Ddiff&rev1=3D17=
&rev2=3D18

Comment:
moved

  <<Include(EditTheWiki)>>
  =

- =3D Contributing to Apache CouchDB =3D
+ This page has moved to https://cwiki.apache.org/confluence/display/COUCHD=
B/Source+Control
  =

- This page explains how you can contribute to Apache CouchDB.
- =

- Apache CouchDB committers, see the CommitPolicy.
- =

- First, thanks for considering to help out, your contributions are appreci=
ated! :)
- =

- =3D=3D Identify Work =3D=3D
- =

- [[http://issues.apache.org/jira/COUCHDB|JIRA]] and the [[http://mail-arch=
ives.apache.org/mod_mbox/couchdb-dev/|mailing list]] are great places to st=
art!
- =

- =

- =3D=3D Fork =3D=3D
- =

- Fork the official Apache CouchDB project mirror with git, the chosen revi=
sion control system for the CouchDB project. There are many places to clone=
 the code from:
- =

-  * from the [[http://git-wip-us.apache.org/repos/asf/couchdb|official Apa=
che servers]]
-  * on [[http://github.com/apache/couchdb|GitHub]]
- =

- For example, to fork the CouchDB repository, and set up a new local branc=
h that tracks master, from your shell you would run:
- =

- {{{
- $ git clone http://git-wip-us.apache.org/repos/asf/couchdb.git
- $ cd couchdb
- $ git checkout -t origin/master
- }}}
- =

- =3D=3D Working in git =3D=3D
- =

- The CouchDB community encourages a certain type of workflow within git. H=
owever, the below are only guidelines.
- =

- =3D=3D=3D Topic Branch =3D=3D=3D
- =

- A good habit to get into is using topic branches for your work, while kee=
ping the master branch untouched. You can then keep the master branch up-to=
-date with the main repository without worrying about merge conflicts.
- =

- =3D=3D=3D=3D Reduce Merge Conflicts =3D=3D=3D=3D
- =

- By not working on the master branch, you ensure that the branch's history=
 will not diverge from the main repository's master branch. This allows you=
 to pull in updates from the main repository without merge conflicts.
- =

- =3D=3D=3D Organize and Isolate Contributions =3D=3D=3D
- =

- By creating a topic branch for each contribution, you effectively isolate=
 your changes into a single branch of history. As long as the topic branch =
is up-to-date, your changes will merge cleanly into the main repository. If=
 your contributions cannot be merged cleanly, the repository maintainer may=
 have to reject your contribution until you update it.
- =

- =3D=3D=3D Easier for the Maintainer =3D=3D=3D
- =

- Maintainers like topic branches. It is easier to review the pull request =
and merge commits into the main repository.
- =

- =3D=3D=3D Git Workflow =3D=3D=3D
- =

- Consider that you've decided to work on JIRA ticket #123 for the CouchDB =
repository. You are charged with updating a INI file.
- =

- =3D=3D=3D=3D Update your master branch =3D=3D=3D=3D
- =

- 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 com=
mits from the canonical ASF repo (origin) and then merging them as a fast-f=
orward 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.
- =

- =3D=3D=3D=3D Create a topic branch =3D=3D=3D=3D
- =

- =

- Topic branches should be named {{{<jira-ticket>-[fix|feature]-<short-desc=
ription>}}}. 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
- # 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
- * 123-fix-ini-file
- }}}
- =

- This topic branch is now isolated and branched off the history of your ma=
ster branch, which also matches the current master branch in ASF. Everybody=
's cool with this.
- =

- =3D=3D=3D=3D Make File Changes =3D=3D=3D=3D
- =

- Let's update the textfile:
- =

- {{{
- $ [ edit etc/couchdb/default.ini.tpl.in ]
- $ git status
-   modified: etc/couchdb/default.ini.tpl.in
- }}}
- =

- `git status` shows that you have modified one file.
- =

- =3D=3D=3D=3D Commit the File Changes =3D=3D=3D=3D
- =

- `git add` will stage the file changes. You can then commit the staged fil=
e(s) with git commit. This is always the process to make changes to a git r=
epository: stage, then commit.
- =

- {{{
- $ git add etc/couchdb/default.ini.tpl.in
- $ git status
- $ git commit -m "Added the new foobar setting."
- }}}
- =

- Alternatively, you could combine staging and committing by using `git com=
mit -am "...."`
- =

- =3D=3D=3D=3D Commit More File Changes =3D=3D=3D=3D
- =

- {{{
- $ [ edit etc/couchdb/default.ini.tpl.in ]
- $ git commit -am "Fix typo in foobar setting comments."
- }}}
- =

- =3D=3D=3D=3D Updating CHANGES and NEWS =3D=3D=3D=3D
- =

- Once you are happy with your changes, you should also update the CHANGES =
and/or NEWS file in the source root directory. The CHANGES file contains in=
formation about all changes, the target audience is developers that want to=
 have a quick overview what got changed/fixed in a release. The NEWS file c=
ontains less information and should give a broad overview of what's happeni=
ng in a release. Think of NEWS as a list that can be used to announce a new=
 release.
- =

- =

- =3D=3D=3D=3D Prepare to Send Pull Request =3D=3D=3D=3D
- =

- Before sending the pull request, you should ensure that your changes merg=
e cleanly with the main repository. You can do this by pulling the latest c=
hanges 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 origin master
- $ git checkout 123-fix-ini-file
- $ git rebase master
- }}}
- =

- 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 ord=
er, to make things clean and tidy. This results in a nice clear linear hist=
ory on the public repos. The [[http://book.git-scm.com/4_rebasing.html|git =
community book has an excellent chapter on rebasing]].
- =

- Merge to master should be done in consultation with our git gurus. You kn=
ow who they are!
- =

- Last thing is to make your code changes available from your fork, and pus=
h them up to either the ASF repo (if you are a committer), or to your own r=
epo (e.g. on github) if you are not a committer.
- =

- {{{
- $ git checkout 123-fix-ini-file
- $ git push origin 123-fix-ini-file
- }}}
- =

- =3D=3D=3D=3D Sharing your Changes =3D=3D=3D=3D
- =

- By pushing your topic branch onto your fork, a CouchDB maintainer can rev=
iew and merge the topic branch into the main repository.
- =

- =3D=3D=3D=3D Sending a Pull Request from GitHub =3D=3D=3D=3D
- =

- Pull requests sent to the [[http://github.com/apache/couchdb|Apache GitHu=
b repositories]] should forward a pull request e-mail to the dev mailing li=
st. It is strongly recommended that you sign up for the mailing list before=
 issuing a pull request and make sure the list is notified. Thanks :)
- =

-  * Open a web browser to your GitHub account's CouchDB fork.
-  * Select your topic branch so that the pull request references the topic=
 branch.
-  * Click the Pull Request button.
- =

- =3D=3D=3D=3D Notifying the Mailing List =3D=3D=3D=3D
- =

- Optionally, you may wish to comment on and advocate for your changes on l=
ist. We highly suggest you sign up for the dev mailing list!
- =

- =3D=3D=3D While Waiting, Continuing Crafting Commits =3D=3D=3D
- =

- Since you worked on the topic branch instead of the master branch, you ca=
n continue working while waiting for the pull request to go through.
- =

- Be sure to create the topic branch from master.
- =

- {{{
- $ git checkout master
- $ git pull origin master
- $ git checkout -b document_blahfasel_setting
- $ git branch -a
- * document_blahfasel_setting
-   master
-   123-fix-ini-file
- }}}
- =

- =3D=3D=3D When Your Pull Request is Accepted =3D=3D=3D
- =

- {{{
- $ git checkout master
- $ git pull origin master
- $ git log
- ( hey there's me! ya! )
- }}}
- =

- You can now delete your topic branch, because it is now merged into the m=
ain repository and in the master branch.
- =

- {{{
- $ 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 :123-fix-=
ini-file).
- =

- =3D=3D=3D If Your Pull Request is Rejected =3D=3D=3D
- =

- In this case, you just need to update your branch from the main repositor=
y and then address the rejection reason.
- =

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