[Couchdb Wiki] Update of "ContributorWorkflow" by andywenk

[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 andywenk:
https://wiki.apache.org/couchdb/ContributorWorkflow?action=diff&rev1=17&rev2=18

Comment:
moved

  <<Include(EditTheWiki)>>
  
- = Contributing to Apache CouchDB =
+ This page has moved to https://cwiki.apache.org/confluence/display/COUCHDB/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 appreciated! :)
- 
- == Identify Work ==
- 
- [[http://issues.apache.org/jira/COUCHDB|JIRA]] and the [[http://mail-archives.apache.org/mod_mbox/couchdb-dev/|mailing list]] are great places to start!
- 
- 
- == Fork ==
- 
- Fork the official Apache CouchDB project mirror with git, the chosen revision 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 Apache servers]]
-  * on [[http://github.com/apache/couchdb|GitHub]]
- 
- For example, to fork the CouchDB repository, and set up a new local branch 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
- }}}
- 
- == Working in git ==
- 
- The CouchDB community encourages a certain type of workflow within git. However, the below are only guidelines.
- 
- === Topic Branch ===
- 
- A good habit to get into is using topic branches for your work, while keeping the master branch untouched. You can then keep the master branch up-to-date with the main repository without worrying about merge conflicts.
- 
- ==== Reduce Merge Conflicts ====
- 
- 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.
- 
- === Organize and Isolate Contributions ===
- 
- 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.
- 
- === Easier for the Maintainer ===
- 
- Maintainers like topic branches. It is easier to review the pull request and merge commits into the main repository.
- 
- === Git Workflow ===
- 
- 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. 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.
- 
- ==== Create a topic branch ====
- 
- 
- 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
- # 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 master branch, which also matches the current master branch in ASF. Everybody's cool with this.
- 
- ==== Make File Changes ====
- 
- 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.
- 
- ==== Commit the File Changes ====
- 
- `git add` will stage the file changes. You can then commit the staged file(s) with git commit. This is always the process to make changes to a git repository: 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 commit -am "...."`
- 
- ==== Commit More File Changes ====
- 
- {{{
- $ [ edit etc/couchdb/default.ini.tpl.in ]
- $ git commit -am "Fix typo in foobar setting comments."
- }}}
- 
- ==== Updating CHANGES and NEWS ====
- 
- 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 information 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 contains less information and should give a broad overview of what's happening in a release. Think of NEWS as a list that can be used to announce a new release.
- 
- 
- ==== Prepare to Send Pull Request ====
- 
- 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 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 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]].
- 
- 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, 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 123-fix-ini-file
- $ git push origin 123-fix-ini-file
- }}}
- 
- ==== Sharing your Changes ====
- 
- By pushing your topic branch onto your fork, a CouchDB maintainer can review and merge the topic branch into the main repository.
- 
- ==== Sending a Pull Request from GitHub ====
- 
- Pull requests sent to the [[http://github.com/apache/couchdb|Apache GitHub repositories]] should forward a pull request e-mail to the dev mailing list. 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.
- 
- ==== Notifying the Mailing List ====
- 
- Optionally, you may wish to comment on and advocate for your changes on list. We highly suggest you sign up for the dev mailing list!
- 
- === While Waiting, Continuing Crafting Commits ===
- 
- Since you worked on the topic branch instead of the master branch, you can 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
- }}}
- 
- === When Your Pull Request is Accepted ===
- 
- {{{
- $ 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 main 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).
- 
- === If Your Pull Request is Rejected ===
- 
- In this case, you just need to update your branch from the main repository 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
- }}}
-