Differences between revisions 18 and 19
Revision 18 as of 2013-05-06 19:07:52
Size: 6391
Editor: AndrewGrieve
Comment:
Revision 19 as of 2013-05-09 15:02:46
Size: 7011
Comment:
Deletions are marked like this. Additions are marked like this.
Line 65: Line 65:
git cherry-pick COMMIT_HASH git cherry-pick -x COMMIT_HASH # the -x flag adds "cherry-picked from <commit>" to the commit messages
Line 79: Line 79:

=== Caveats of Rebasing ===

It's important to note when rebasing that the commits must never have been pushed or pulled before. If they have been, they will be duplicated in the history. The code should survive just fine, but the history will be a confusing tangle, especially if this happens multiple times.

Note also that the timestamp on a commit will be unchanged by a rebase, but that it will appear "out of order" in git log. This is because git log is not chronological order, but in order of the `parent` chain of the commits.

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. Once you've chosen a password, test out your credentials with the following:

git checkout master
git pull apache master
git push apache master

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 You Homework

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

Committing Your Own Changes

Step 1: Mail the Mailing-list

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.
  • The "Fix For" field is used for the purpose of Release Notes.
  • The issues are also used to track which commits / topic branches are related to them.

Step 3: Create a topic branch

  • Using a public topic branch is necessary only when either:
    1. you would like to collaborate on the feature
    2. you would like feedback on your code before committing
  • For small bugfixes, public topic branches are not required.
  • Note: You should never rebase a public topic branch!

Step 4: Ask for a code review

  • If you are using a public topic branch, then you should ask for a code review when you consider it to be complete.
  • For now, use a github pull request. Soon, use reviews.apache.org.

  • Email the ML so that anyone who is available can have a look at your code. If you have someone in particular that you would like approval from, be sure to add them in the To: of your email.
  • Again, sometimes this will end with a Lazy Consensus.

Step 5: Merge your change

  • Once your topic branch is tested & working, it's time to merge it.

  • Rebase & commit it to master. If it fixes a regression, then also cherry-pick it into the appropriate release branch.

  • Here is an example workflow for committing a change:

git checkout master
git pull apache
git checkout topic_branch
git rebase master -i
git checkout master
git merge --ff-only topic_branch
git push apache master
git branch -d topic_branch
# Cherry-pick:
git checkout 2.6.x
git cherry-pick -x COMMIT_HASH  # the -x flag adds "cherry-picked from <commit>" to the commit messages
git push apache 2.6.x

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

Commit A: Implemented RockOn feature (CB-1234)
Commit B: Added tests for RockOn (CB-1234)
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. Having a smaller number of commits when merging makes it easier for others to comprehend the diff commits, and also makes it easier to roll-back commits should the need arise. For JS commits, prefix the message with [platform] so that it's clear who should take interest in the commit. For all commits, be sure to include the JIRA issue number / URL.

Caveats of Rebasing

It's important to note when rebasing that the commits must never have been pushed or pulled before. If they have been, they will be duplicated in the history. The code should survive just fine, but the history will be a confusing tangle, especially if this happens multiple times.

Note also that the timestamp on a commit will be unchanged by a rebase, but that it will appear "out of order" in git log. This is because git log is not chronological order, but in order of the parent chain of the commits.

Step 6: Update JIRA

Mark the relevant JIRA as fixed, and be sure to include the relevant commit IDs.

Processing Pull Requests

Step 1: Review the change

  • View the user's branch in github and request changes be made (if applicable) by adding comments in the web interface

Step 2: Ensure that they have signed the Contributor Agreement

Step 3: Merging the change

Run the following:

git remote add foo git://github.com/TheirUserName/cordova-docs.git
git fetch foo
git cherry-pick 5d3e1b6 # For each commit ID in their branch.
git rebase origin/master -i

The last step will let you interactively review the changes being made to master. You should:

  • Squash as many commits as is reasonable together.
  • Re-write commit messages to include JIRA issue numbers in the form [CB-####]

Step 4: Check the author

git keeps track of the author of commits separately from the committer of the commit.

Typically, both of these values are set to the person submitting the pull request. After your pull/merge/rebase/whatever work, you may find the values have changed - or not. What we would typically be looking for is the final commit to have YOU as the committer and the original author as the author.

You can check these fields with the following command:

git log --pretty=full

If the author is set to YOU, and you'd like to reset it to the original author, you can amend the commit:

git commit --amend --author=some_author_id_here

If the committer is NOT set to YOU, and you'd like to reset it to yourself, well, not sure. I think the idea would be to do an extra merge, maybe on a new branch, probably with --no-ff (preventing a fast-forward), and then a commit --amend from there if the author got reset to you.

git commit --amend --author=SomeAuthorIdHere

Step 5: Push the change

git push apache master

Step 6: Final details

  • Update related JIRA issue with the commit ID and close it if appropriate.
  • Respond to pull request on github with link to their commit and ask them to close the pull request.

CommitterWorkflow (last edited 2014-03-13 03:02:16 by AndrewGrieve)