[Cordova Wiki] Update of "GitWorkflow" by JoshSoref

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Cordova Wiki" for change notification.

The "GitWorkflow" page has been changed by JoshSoref:
https://wiki.apache.org/cordova/GitWorkflow

Comment:
Extract Get content to GitWorkflow

New page:
= 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:

 * from the [[http://git-wip-us.apache.org/repos/asf|official Apache servers]]
 * on [[http://github.com/apache|GitHub]] (type "[[https://github.com/search?q=%40apache+cordova|cordova]]" into the "Find a Repository" box)

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.
 1. 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 [[http://cordova.apache.org|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.
 1. 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).
 1. 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.
 1. 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 [[http://cordova.apache.org/#mailing-list|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.

[[https://reviews.apache.org/groups/cordova/|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 [[https://issues.apache.org/jira/browse/CB#selectedTab=com.atlassian.jira.plugin.system.project%3Acomponents-panel|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 :CB-1234
}}}
I know, deleting a remote topic branch is ugly (git push origin :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.