Differences between revisions 35 and 36
Revision 35 as of 2013-11-07 22:57:17
Size: 7911
Editor: JoshSoref
Comment: Explain the `dev` branch designation
Revision 36 as of 2013-11-07 23:38:17
Size: 7935
Editor: JoshSoref
Comment: improve disambiguate plugman text
Deletions are marked like this. Additions are marked like this.
Line 160: Line 160:
   * Through '''Cordova 3.0''', `plugman` installs from `master`, which means we couldn't use it for development.
   * Post Cordova 3.0, there is registry support...
   * Through '''Cordova 3.0''', `plugman` installed from `master`, which means we couldn't use `master` for development.
   * Post '''Cordova 3.0''', `plugman` has support for a registry...

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
cd cordova-coho
npm install
cd ..
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.

    • You will need a Review Board userid and password. One can be requested from the site.
    • 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.
    • To create your review request is to use post-review (RBTools) from the repo with the change, only if the repo contains the file '.reviewboardrc'

      • Currently the following repos contain .reviewboardrc: cordova-coho cordova-cli cordova-android cordova-ios cordova-js
    • If you don't want to use post-review tool, then on the web site:
      • Click "New Review Request"
      • On your workstation do a git diff and pipe the output to a file. In the new request, select the git repo, the base dir where you did the diff, upload the diff file you created, and click Create.
      • On the next web page, fill in the description text, the name of the Branch (i.e., "master"), the Bug (i.e., "CB-4960"), the Description and the Testing Done fields. If you want a review from a specific person, enter their userid / name in the People field. If you want input from the whole community, enter "cordova" in the Groups field. Click the Submit button.
    • After you have received sufficient feedback, click the button to mark your review as Discarded or Submitted [to a stream].
    • If you don't want to use ReviewBoard you can use Github Pull Request

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 the 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

    • Through Cordova 3.0, plugman installed from master, which means we couldn't use master for development.

    • Post Cordova 3.0, plugman has support for a registry...


  • Commit all changes to branch: master


  • Commit all changes to branch: master


  • Commit all changes to branch: master

Processing Pull Requests

See ProcessingPullRequests