Fork

Fork the official Apache Cordova project mirror with git. Git is the chosen revision control system for the Cordova project. There are many places to clone the code from:

There are 50+ git repositories for Cordova. Their names all begin with "cordova-". Be aware that "cordova-windows-phone" is an alias for "cordova-wp8".

Committers will typically fork from the official Apache server, since they are authorized to commit directly back to it. This is the authoritative / official repo.

However, contributors should typically fork from GitHub. This makes it easy to submit pull requests, which is the preferred method to make contributions as a non-committer. So as a contributor you should:

  1. Create an account on github.com. Note that your repositories will have a URL of the form 'https://github.com/you' where the string 'you' is your userid. For the exercise here, substitute 'you' with your github userid. The official github repos that are read-only are at https://github.com/apache.

  2. Note that Cordova has each component in a separate git repository, so there are many git repositories that compromise the entire project. They all start with "cordova-". So for this exercise we will use the fake name "cordova-x", which you should replace with the specific repository(s) you want to work with, such as "cordova-docs" or "cordova-android". The full list is on the Cordova home page. Note that all of the 18 core plugins are each in their own separate repo. This does make for more repos than you may be used to.

  3. On the GitHub web interface, fork github.com/apache/cordova-x.git to your own account on GitHub (ie, github.com/you/cordova-x.git).

  4. From your workstation, clone your GitHub repo (ie, github.com/you/cordova-x.git) to your workstation. For example, to clone a Cordova repository, from your workstation shell you would run (note the "https" protocol):

    $ git clone https://github.com/you/cordova-x.git
    You should now have a "cordova-x" directory with the extracted source.
  5. Add a pointer back to the official repo:
    $ cd cordova-x
    $ git remote add apache https://git-wip-us.apache.org/repos/asf/cordova-x.git

Here is a diagram of the repos and their flows:

http://cordova.apache.org/wiki-images/contributor-git.png

If you want to simply check out the source code and don't plan on making contributions, then you can skip GitHub and clone directly from the Apache servers:  $ git clone https://git-wip-us.apache.org/repos/asf/cordova-x.git 

Working in git

The Cordova 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.

Getting Noticed

It is strongly recommended that you sign up for the mailing list before issuing a pull request. If your pull request is related to an existing JIRA issue, then add a comment to the issue with a link to your pull request. If it's not (or you're feeling too lazy to search through JIRA), then you should email the mailing-list to notify committers of your pull request.

Adding the URL of your pull request into the Jira item with some verbage saying it is ready will help notify a committer that your topic branch is ready. Most committers will get email notifications regarding all Jira items. You may also want to send an email to the mailing list explaining what your changes do and advocating for it.

Review Board is a tool for committers to review each others' changes. As a contributor generally you won't use Review Board - the pull request should be sufficient.

A list of the lead committers for each component can be found listed in Jira. But generally you should send an email to the whole mailing list, not to the individual lead committers because this is a community.

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 apache master
$ git checkout -b fix_ugly_vibrate_example
$ git branch -a
* fix_ugly_vibrate_example
  master
  CB-1234

When Your Pull Request is Accepted

$ git checkout master
$ git pull apache master
$ git log | more
  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.

PLEASE delete your topic branch on github origin, as that will automatically close your pull request. Alternatively, from the github web interface you can close your pull request while leaving your topic branch present. The goal here is for pull requests to be closed after they are merged, so we don't end up with a bunch of pull requests that appear unresolved.

$ git branch -d CB-1234
$ git push origin --delete CB-1234

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 apache master
$ git checkout CB-1234
$ git rebase master
( edit, commit, edit, commit, etc...)
$ git push origin CB-1234

Then delete your topic branch (or close your pull request) as described above.

GitWorkflow (last edited 2014-06-04 17:37:44 by MarcelKinard)