Differences between revisions 28 and 29
Revision 28 as of 2013-09-04 12:20:35
Size: 6536
Editor: MichalMocny
Revision 29 as of 2013-09-04 12:26:04
Size: 6535
Editor: MichalMocny
Deletions are marked like this. Additions are marked like this.
Line 54: Line 54:
 * You are responsible for testing the changes that push.  * You are responsible for testing the changes that you push.
Line 65: Line 65:
   * Easiest way is to use type [[http://www.reviewboard.org/docs/rbtools/dev/|post-review]] from the repo with the change.    * Easiest way is to use [[http://www.reviewboard.org/docs/rbtools/dev/|post-review]] from the repo with the change.
Line 103: Line 103:
git push apache 2.9.x git push origin 2.9.x

First Steps

Congratulations! You've gained the confidence of your fellow Cordova committers and have been granted the ability to commit code directly, and to apply pull requests from others. You should receive an email from our Apache mentor with the details of how to setup your account.

Configure your git repos

It's convenient to have the origin of your git repos to point to Apache's repos (as opposed to your clone of them on github). The easiest way to do this is to delete them and re-clone them using coho:

git clone https://git-wip-us.apache.org/repos/asf/cordova-coho.git
cordova-coho/coho repo-clone -r plugins -r mobile-spec -r ...

Test out your credentials with the following:

git pull
git push

If all goes well, git push should have asked you for your username and password, and an "Everything up-to-date" message should have been printed.

Join the private mailing-list

Send an email to private-subscribe@cordova.apache.org. Note that this is a moderated list, so your request to join must be manually accepted.

Do Your Homework

Read through: http://www.apache.org/dev/committers.html

Committing Changes

Step 1: Mail the Mailing-list (''optional'')

This is required if any of the following are true:

  • Your change will add/remove/change any public Cordova APIs
  • You suspect that your change has a chance of being controversial
  • You would like feedback before you begin

When possible, try to phrase things in the form of a proposal. If no one objects (within a workday or two), then consider yourself to have Lazy Consensus.

Step 2: Ensure there is a JIRA issue.

  • JIRA issues are used for both new features and for bugs.

Step 3: Create a topic branch (''optional'')

  • Using a public topic branch is necessary only when you would like to collaborate on the feature.
  • For small changes, private topic branches are preferred.
  • Note: You should never rebase a public topic branch!

Step 4: Make your changes

  • Thank you for making the world a better place.
  • If your change adds a new feature, or makes a non-backwards-compatible change, please note it in the commit description!

Step 5: Test your changes

  • You are responsible for testing the changes that you push.
  • This includes:
    • All automated tests in mobile-spec
    • Manual tests in mobile-spec that might be affected by the change
    • Platform-specific unit tests (i.e., cordova-android/test, cordova-ios/CordovaLibTests, cordova-js: grunt test, cordova-plugman: npm test)

  • If there is no existing test that exercises your code, add one!
  • If you are writing documentation (i.e., cordova-docs), be aware of the style guidelines.

Step 6: Ask for a code review (''optional'')

  • Do this if you want a second pair of eyes to look at your code before it goes in.
  • Use reviews.apache.org to create a review request.

    • Easiest way is to use post-review from the repo with the change.

    • By default, the ML will be notified of your review request.
    • If you have someone in particular that you would like approval from, be sure to add them in "People" field of the review.

Step 7: Push your change

  • Rebase & commit it to the appropriate branch (see "Which Branch to Commit To" below).

  • If it fixes a regression, then also cherry-pick it into the appropriate release branch.
  • Here is an example workflow for committing a change when you've made it on a topic branch:

git pull
git checkout topic_branch
git rebase master -i
git checkout master
git merge --ff-only topic_branch
git push
git branch -d topic_branch
  • Here is an example workflow for committing a change when you've made it on master:

git pull --rebase
git rebase origin/master -i
git push
  • If you ever end up with a merge commit on master that you don't want:

git rebase origin/master
  • If you need to add your change to a release branch:

git checkout 2.9.x
git cherry-pick -x COMMIT_HASH  # the -x flag adds "cherry-picked from <commit>" to the commit messages
git push origin 2.9.x

The git rebase -i step is your chance to clean up the commit messages and to combine small commits when appropriate. For example:

Commit A: [CB-1234] Implemented RockOn feature
Commit B: [CB-1234] Added tests for RockOn
Commit C: Fixed RockOn not working with empty strings
Commit D: Renamed RockOn to JustRock
Commit E: Refactor MainFeature to make use of JustRock.
  • In this case, it would be appropriate to combine commits A-D into a single commit, or at least commits A & C.

  • Fewer commits are better because:
    • Easier to comprehend the diff
    • Makes changelog more concise
    • Easier to roll-back commits should the need arise

  • For all commits:
    • Prefix with JIRA IDs: [CB-1234]
  • For cordova-js commits:
    • Prefix the message with [affected_platform] so that it's clear who should take interest in the commit
    • e.g.: [CB-1234] [android] Improved exec bridge by using strings instead of JSON
    • e.g.: [CB-1234] [all] Fixed plugin loading paths that start with /.

Step 8: Update JIRA

  • An Apache bot should have already added a comment to the issue with your commit ID (based on the CB-1234 being in the commit message).
  • Close the issue, and set the "Fix Version" field.
    • The "Fix Version" field is used for the purpose of Release Notes, and should be set to the CadVer

Which Branch to Commit To

Platforms, mobile-spec, cordova-js, cordova-docs:

  • Commit all changes to branch: master

  • If it fixes a regression, cherry-pick into the release branch (see CuttingReleases)

    • e.g. To cherry pick the last commit from master: git cherry-pick -x master

Core Plugins:

  • Commit all changes to branch: dev

    • Since plugman currently installs from master, we can't use it for development.


  • Commit all changes to branch: master


  • Commit all changes to branch: master

Processing Pull Requests

See ProcessingPullRequests