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 JanLehnardt
Date Sat, 25 Feb 2012 21:02: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 JanLehnardt:
http://wiki.apache.org/couchdb/ContributorWorkflow?action=diff&rev1=9&rev2=10

Comment:
new git workflow

- ## page was renamed from How_to_contribute_(for_Non-Committers)
  <<Include(EditTheWiki)>>
  
- Thanks for your interest in growing CouchDB! This page will explain the process of submitting
code to fix issues or add features.
+ = Contributing to Apache CouchDB =
  
+ This page explains how you can contribute to Apache CouchDB.
- In this document:
-  * [[#pre|Prerequisites]]
-  * [[#step1|Step 1: See if your bug/feature exists in JIRA]] 
-  * [[#step2|Step 2: Run the tests]]
-  * [[#step2|Step 3: Go forth and code!]]
-  * [[#step3|Step 4: Create and Upload a Patch]]
-  * [[#questions|Asking Questions And Getting Feedback]]
  
+ First, thanks for considering to help out, your contributions are appreciated! :)
- <<Anchor(pre)>>
- == Prerequisites ==
- Ensure that you've
-  * Installed from source: [[Installing_from_source]]
-  * Got your system running in Dev mode: [[Running CouchDB in Dev Mode]]
  
+ == Identify Work ==
- <<Anchor(step1)>>
- == Step 1: See if your bug/feature exists in JIRA ==
-  * JIRA is the issue tracker that CouchDB uses to track items of work.
-  * Visit https://issues.apache.org/jira/browse/COUCHDB to see if your issue already exists.

-  * If it doesn't, you can open one by
-   * Registering for a JIRA account here: https://issues.apache.org/jira/secure/Signup!default.jspa
-   * Then opening a new issue here: https://issues.apache.org/jira/secure/CreateIssue!default.jspa
-  * Either way, bookmark the link because you'll need it to comment or submit patches.
  
- '''Note:''' You're still welcome to submit patches even if an issue has been assigned to
someone else. In this case, it's probably better to add a comment before getting started.

+ [[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!
  
- <<Anchor(step2)>>
- == Step 2: Run the tests ==
-  * Instructions are here: http://wiki.apache.org/couchdb/How_to_create_tests?action=show

-  * Run the tests at least before you start coding and when you're done.
  
+ == Fork ==
- <<Anchor(step3)>>
- == Step 3: Go forth and code! ==
-  * Take a look at the recommended coding standards here: [[Coding_Standards]]
-  * Before starting, make sure that your local copy is up to the latest version
-  * For those using the command-line subversion tools, run this before starting:
-  {{{
- $ cd YOUR-COUCHDB-CHECKOUT-DIR
- $ svn update
-  }}}
-  * Don't forget to rebuild couchdb afterwards
-  {{{
- $ cd YOUR-COUCHDB-CHECKOUT-DIR
- $ make dev
-  }}}
  
+ Fork the official Apache Cordova project mirror with git, the chosen revision control system
for the Cordova project. There are many places to clone the code from:
- <<Anchor(step4)>>
- == Step 4: Create and Upload a Patch ==
-  * Once you've completed the feature/fix you will need to create a patch
-  * From the command line, call the following, giving your patch a name:
-  {{{
- $ cd YOUR-COUCHDB-CHECKOUT-DIR
- $ svn diff > your_patch_file_name.patch
-  }}}
-  * Open up the issue link you found/created in Step 1
-  * Click on '''Attach File''' under the '''Operations''' menu on the left
-  * Add your file and add a comment about the change.
  
- And you're done!
+  * 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, from your shell you would run:
- <<Anchor(questions)>>
- == Asking Questions And Getting Feedback ==
- You can contact the CouchDB developers to ask questions and propose ideas by:
-  * Sending a mail to the Dev mailing list: http://wiki.apache.org/couchdb/Mailing_lists
or,
-  * Chatting on IRC: #couchdb on Freenode (irc.freenode.net)               
  
- All issues created in JIRA are mailed to the Dev mailing list.
+ {{{
+ $ git clone http://git-wip-us.apache.org/repos/asf/couchdb.git
+ }}}
  
+ == 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 ticket #11 for the CouchDB repository. You are charged
with updating some text file.
+ 
+ ==== Update your master branch ====
+ 
+ We're assuming you have cloned the docs 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.
+ 
+ {{{
+ $ git checkout master
+ $ git pull cordova master
+ $ git push origin master
+ }}}
+ 
+ ==== Create a topic branch ====
+ 
+ Let's create a new branch based off of master and call it "ticket_11".
+ 
+ {{{
+ $ git checkout master
+ $ git checkout -b ticket_11
+ $ git branch
+   master
+ * ticket_11
+ }}}
+ 
+ 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.
+ 
+ ==== Make File Changes ====
+ 
+ Let's update the accelerometer documentation for the "watchPosition" function.
+ 
+ {{{
+ $ [ 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."
+ }}}
+ 
+ ==== Prepare to Send Pull Request ====
+ 
+ Before sending the pull request, you should ensure that your changes merge cleanly with
the main documentation repository.
+ 
+ {{{
+ $ git checkout master
+ $ git pull couchdb master
+ $ git checkout ticket_11
+ $ 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]].
+ 
+ Alternatively, you can use git merge master instead of git rebase master, but your topic
branches history may not be as clean.
+ 
+ Last thing is to make your code changes available from your fork.
+ 
+ {{{
+ $ git checkout ticket_11
+ $ git push origin ticket_11
+ }}}
+ 
+ ==== 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 couchdb master
+ $ git checkout -b document_blahfasel_setting
+ $ git branch -a
+ * document_blahfasel_setting
+   master
+   ticket_11
+ }}}
+ 
+ === When Your Pull Request is Accepted ===
+ 
+ {{{
+ $ git checkout master
+ $ git pull couchdb 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 ticket_11
+ $ git push origin :ticket_11
+ }}}
+ 
+ I know, deleting a remote topic branch is ugly (git push origin :ticket_11).
+ 
+ === 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 couchdb master
+ $ git checkout ticket_11
+ $ git rebase master
+ ( edit / commit / edit / commit)
+ $ git push origin ticket_11
+ }}}
+ 

Mime
View raw message