This article outlines the standard git and GitHub process, and workflow for working with AeroGear examples, and repositories. Any repository specific requirements will be listed in the repository, and/or will be linked in the document.
Go to github and create an account
Use GitHub’s forking feature to get a copy of the repository into your account. AeroGear has multiple repositories available. Choose the one (or more) that you wish to contribute to.
Now that you have your own copy in GitHub you need to get it on your local system.
$ git clone git@github.com:[your user]/[chosen repo].git
Cloning into [chosen repo]...
remote: Counting objects: 291, done.
remote: Compressing objects: 100% (175/175), done.
remote: Total 291 (delta 90), reused 273 (delta 72)
Receiving objects: 100% (291/291), 264.03 KiB | 295 KiB/s, done.
Resolving deltas: 100% (90/90), done.This is used for pulling in future updates, and keeping your repository up to date.
$ git remote add upstream git://github.com/aerogear/[chosen repo].gitIt is a good practice to regularly pull in updates from the upstream repo before starting any work. Especially if your local copy is stale.
$ git checkout master
$ git pull upstream masterIt is a good practice to do any work in a topic branch to keep your master branch clean. The rest of this document will assume you are using it.
$ git checkout -b <your-topic-branch>If you have not done so it is a good idea to communicate any planned bug fixes, or updates you wish to make with the community and project team. See Contributing To AeroGear for more on the best ways to do that.
$ git commit -m "Your commit message. AEROGEAR-XX"
$ git commit -m "Your other commit. AEROGEAR-XX"If the changes you are making have a corresponding jira (and they should) add the Jira ID to the commit message.
This is a good time to talk about the recommended way of scoping the work for a commits, and pull requests.
1 pull request should represent 1 issue, or feature
It should be represented by a jira or be trivial in nature
Exceptions can be made for technically related, and/or trivial issues
Multiple commits and issues
Commits don’t need to be squashed into a single commit per issue
Trivial commits should be squashed though
Examples:
"Fixed one spelling mistake"
"Reset my type"
"Brainfart"
In general commits should be meaningful, and provide value to the history
For tips on squashing commits see the related section below.
Misc
Any whitespace only changes ( such as indentation updates, tab-->space, etc.. ) should be in their own commit and/or pull request.
If this is not done separating out the code changes from the whitespace updates is very difficult.
All your changes are done, and you think you’re ready to get your updates seen.
As you are working on your branch others may have updated the upstream repository. You must synchronize with those changes by rebasing, before creating the pull request. This will apply your changes on top of any changes from upstream.
In your topic branch:
$ git fetch upstream
$ git rebase upstream/masterAt this point you may run into conflicts depending on what was changed locally and upstream. You will need to resolve any of those conflicts (try git mergetool) and rerun the rebase command. You can abort a rebase as well with the git rebase --abort command.
Now that you’re sync’ed with upstream, and your changes are on top of upstream master you are ready to push your local updates to your forked GitHub repository.
$ git push <your-fork> <your-topic-branch>The push command defaults to your master branch not your current branch, so specifying your topic branch is needed to get it pushed.
The "-f" push option may be needed depending on the results of the rebase above.
Now your updates are in your repo, and ready to share. The next step is to let the project know about them.
Create a pr against the upstream repo using the steps described by github
At this point you can update the related jira issue to "Pull Request Sent" status. There are a couple of options on what to do for your next step depending on the situation.
Pull request is not blocking work, and/or not time sensitive
Will be picked up my the team developed within a couple of days and reviewed.
Pull request is blocking additional work, and/or is time sensitive, and/or critical
Email the aerogear-dev mailing list and post that this PR should be reviewed and why
Join the #aerogear channel @ irc.freenode.net, and request someone review this PR
In any of these situations please keep an eye out for any comments, or follow up items related to your pull request so that we can act on them quickly. GitHub and the pull request mechinism will be used for code reviews, and comments. Please act on these comments in timely manor so we can get your changes in!
See How to Handle AeroGear Pull Requests for more on handling pull requests.
Awesome! Your pull request has been merged, the jira is closed, and you are basking in the after contributing to an open source project glow!
Before the drinks start to flow, be sure to update your local repository, and forked repo with the latest changes that include your pull request. You can also delete, or manage your topic branch as you see fit.
$ git checkout master
$ git pull --rebase upstream masterand then
$ git push <your-fork> masterto update your GitHub fork.