AeroGear GitHub Workflow & Instructions

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.

Get a GitHub account

Go to github and create an account

Fork the desired AeroGear repository

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.

Clone your newly forked copy to your system

Now that you have your own copy in GitHub you need to get it on your local system.

$ git clone[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.

Add a remote reference to the upstream repo

This is used for pulling in future updates, and keeping your repository up to date.

$ git remote add upstream git://[chosen repo].git

Pull in updates from upstream

It 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 master

Create a topic branch

It 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>

Make your changes, and commit them locally

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.

Scoping commits, and pull requests

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.

Prepare for the pull request

All your changes are done, and you think you’re ready to get your updates seen.

Sync with any upstream changes via rebase

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/master

At 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.

Pushing your local changes to your repo

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.

Create the pull request

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

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.

Update your branch once the PR has been closed

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 master

and then

$ git push <your-fork> master

to update your GitHub fork.