The CommCare Mobile team uses GitHub and Git for version control and release management.

If you're coming from Mercurial, I enjoyed this brief primer on the key differences

Background

The mobile development workspace is composed of 2 repositories found here. They are

Place each of these repositories in the same root directory. So my structure is:

workspace

|__ dimagi

|__ commcare-core

|__ commcare-android

Run git clone for each repository, e.g., git clone https://github.com/dimagi/commcare-core.git

Once this is done, you should be able to open all of the code in Android Studio using these instructions.

Branching

To submit any changes, you will need to create a branch to do your work in.

BEFORE beginning work on a task, create a branch for it: git checkout -b my_branch_name

After this, you can list branches with git branch (which will star the branch you're currently working on) and switch between branches using git checkout branch_name Note that you can't leave a branch with uncommitted changes; you must either commit or stash your changes.

To push a given feature, make sure you're in the correct branch and follow the steps below.

Committing changes

This assumes that you've made some changes to the code on your local machine that you want to push to GitHub. The steps are:

  1. cd into the relevant repository
  2. git status to check which files will be submitted, git diff to see their diffs, and git add to add files to the set of files that will be committed.
  3. Any files that you want to commit must be added with git add (or git rm if you're deleting a file). git status will show you which files will be committed and which are still "unstaged." 
  4. Once you're satisfied with the set of files, make sure you're on the correct branch and run git commit -m "commit message here" to submit
  5. Push to GitHub: git push origin my_feature_name This will create a new branch on GitHub with your changes.

Merging your changes via Pull Request

Once you're satisfied with the change set you have (this should be one cohesive unit: IE one bug fix, one feature, one refactor, etc. - not a combination) you'll want to create a pull request to have that code merged into trunk. The process for that is:

  1. Navigate to the repository you want to pull request (PR), e.g., https://github.com/dimagi/commcare-core
  2. Click the green pull request button on the left, above the list of files.
  3. Set the comparison branch to your feature branch.
  4. Once you do this, you should see a list of commits populated at the bottom of the screen. Review this to make sure all are correct. In particular, make sure you aren't accidentally merging or closing any branches.
  5. Click the big green "Create pull request" button.
  6. Fill out the text boxes with a brief description of what you're doing here
  7. Add any appropriate PR tags! They're mostly self-explanatory, but some notes about the most important ones:
    1. "don't pull" – Use this to signify that your changes should not be merged yet
    2. "ready for review" – What it sounds like; on the mobile team, other developers won't review your PR until it has this tag
    3. "minor (quick review)" – Using this will often help your PR get merged faster, because other developers know it won't take them long to review. Use it honestly though!
    4. "Release Note" – Include this tag on the PR for anything that should be included in the "Release Notes" for the upcoming release (what is listed on the Play Store to describe what has changed in the latest release). If you add this tag, also include a comment on the PR with the text of the release note itself.
    5. "announce" – Include this tag on the PR for anything that should be announced internally along with the next release (i.e. stuff that isn't going into the Release Notes but will still be of interest to the users of CommCare that are internal to Dimagi)

Important Note: If you have an outstanding Pull Request that is being reviewed and want to submit a bug fix or another feature that is unrelated to your original PR, this should be done in a new branch.

Code Review

Code Review for PRs you have created:

  • Once your PR is created and marked "ready for review", other coders on the team will review your PR and submit comments and corrections via the GitHub interface. You should receive these as email notifications. 
  • When you receive PR feedback, you can either reply to a comment if it was just a question (or if you have a question/clarification to make), or else make the requested changes locally. Then follow the same procedure as above to push them to your branch, which will make them appear in your PR.
  • When you are done making requested changes to a PR, notify the person (or people) who requested them on the PR, so that they can review what you've changed, and either merge it or request further changes.

Code Review for others' PRs:

  • Responsibility for code review amongst the team is informally shared. Everyone is in general expected to devote a bit of time each week to reviewing PRs that have been marked "ready for review", particularly if someone has indicated that it is time-sensitive. That being said, if you have a particularly busy week, don't sweat it; the goal is just to not have a big pile of PRs still in need of review a few days before code freeze. Admittedly, this is a goal that we are still working toward as a team (smile).

Pulling from Trunk

Basically as often as you think of it, you'll also want to pull master from the trunk to receive other people's updates that have been merged: git pull origin master

Further Reading

That's about all you need to know to get around with the basics of GitHub with Dimagi. Other sometimes useful functions include:

  • Reset: allows you to remove a change set when you want to backtrack.
  • Stash: Sometimes you'll want to save some code for later but not push it to your repo; however, some operations require you to have no outstanding changes. Instead of committing or discarding your changes, you can choose to stash your changes, moving them into temporary storage. Later, you can move them back in with the same menu.
  • Merge: This is an entirely separate subject we won't deal with now
  • No labels