cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <>
Subject [Cordova Wiki] Update of "GitWorkflow" by purplecabbage
Date Mon, 13 Mar 2017 23:30:37 GMT
Dear wiki user,

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

The page "GitWorkflow" has been deleted by purplecabbage:

- = 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 [[|official Apache servers]]
-  * on [[|GitHub]] (type "[[|cordova]]"
into the "Find a Repository" box)
- 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 Note that your repositories will have a URL of the
form '' 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
-  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 [[|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 to your own account
on !GitHub (ie,
-  1. From your workstation, clone your !GitHub repo (ie, to
your workstation. For example, to clone a Cordova repository, from your workstation shell
you would run (note the "https" protocol):
-  {{{
- $ git clone
- }}}
-  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
- }}}
- Here is a diagram of the repos and their flows:
- {{}}
- 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
- = 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.

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message