Git Workflow

If you are not a member of the Cadasta development team, pay particular attention to the section "Working with forks" at the bottom!

Basic workflow

The master branch contains deployable code only.

We never directly commit or push anything to master.

All changes to master are incorporated via GitHub pull requests.

To contribute new code:

Create a new feature branch from the latest version of master. Choose a name that shows what you are working on, e.g.:

For new features: feature/organizations
For bug fixes: bugfix/123-archiving-projects, where 123 is the GitHub issue ID (if one exists).

Commit changes to your feature branch.
Create a pull request once you have completed and tested your work (see below for detailed instructions on creating PRs). The pull request that you create should have all the work on your feature branch squashed into a single commit. (This makes reviewing and managing merge conflicts easier.)
The team will review your contributions and possibly make suggestions for changes. During review, if you need to make updates to your PR, just push new commits to the PR branch. Don't squash those commits, so that the history of the discussion and changes is preserved.
When the team is satisfied with the PR, they will merge your work into master using GitHub's "Squash and merge" feature.

Creating pull requests

Before you create a PR, please do the following:

Pull the latest changes from GitHub to your working copy.
Rebase your topic branch onto the latest master.
Resolve any merge conflicts and ensure that everything still works.
Do an interactive rebase to squash the commits on your feature branch into one commit.
Do a force push to update your feature branch on GitHub.

There are two parts to this; one mandatory and one that makes life much more pleasant later on. Rebasing onto the latest master and checking everything is mandatory. No PR that has merge conflicts or fails any tests will pass review without very good reason. Squashing commits into one is something that makes the history of the repository much more manageable -- in six months time, you won't care exactly what individual steps you took to perform a task, and in the log (and any graphical tools you use) you can see a lot more history if "little" commits are squashed.

Once you have completed these steps, you can create a PR using the "Create pull request" button on GitHub.

Any PR that includes a database migration must be include the relevant information in the body of the PR and be marked with the "Migration" label.

When to squash commits

DO squash commits:

When initially making a PR
When merging PRs (use the "Squash and merge" button in the GitHub UI!)

DON'T squash commits:

During PR discussion threads

Release process

At the end of each sprint, the code on master is presumed to be ready for release.
Before releasing new code at the end of each sprint, we have a one-week feature freeze to perform QA on the new work.
During pre-release freezes only bugfix PRs will be merged into master. Any PRs created during the freeze period will remain open but will not be reviewed or merged until after the release.
At the end of the feature freeze period, there will be a 24-hour code freeze during which time no merges to master will occur (barring emergency hotfixes required for successful migration or deployment). This is to facilitate final testing of migrations and deployment in preparation for the release date.
A go/no-go decision will be made about whether to release the new code (the default should be "go", but if serious problems are discovered during the freeze periods, it may be necessary to delay the release).
Once a release is confirmed, the most recent commit in the current master is tagged with the release version number and is deployed to the demo and production sites.
Bugfixes arising after release will be rolled into the following sprint/release cycle.
Hotfixes to the current release can be created on a new branch from master and deployed as required (which should be relatively rare, since we're going to do releases so often). These hotfixes must also be propagated back into the master branch.

Consequences of this:

The master branch has a dual identity: during normal development, it's our "development" branch into which we merge all new work; during pre-release freeze, it's our "QA" branch into which we merge only bugfixes for the upcoming release. (This should rarely cause confusion, since we'll be communicating with each other about the current state of things anyway.)
If you create a PR that fixes a bug that should be incorporated into the release during the freeze, you must mark your PR with the bugfix label. Only PRs carrying this label will be merged during freeze. All other PRs will be held open until the end of the code freeze.

Working with forks

All the notes above apply to members of the Cadasta development team, who have push access to the main Cadasta/cadasta-platform GitHub repository. If you are not a member of the Cadasta development team, but want to contribute to development of the Cadasta platform, follow these steps:

Create a fork of the Cadasta/cadasta-platform GitHub repository on GitHub.
Clone your fork of the cadasta-platform repository to make a local working copy.
Add the Cadasta/cadasta-platform repository to your local working copy as an upstream remote (see here for help on this).
Choose an issue or feature to work on and make a topic branch from the master branch of your repository: for example, git checkout -b bugfix/#565 or git checkout -b enhancement/sql-optimization. This is important: PRs created from the master branch of your repository will not be accepted!
Work on the issue or feature.
When you are satisfied with your work and want to make a pull request, you must follow the steps in the sections "Creating pull requests" and "When to squash commits" above. Updating the topic branch in your forked repository is a little more complicated because you need to fetch changes from the upstream remote, but the process is something like:

git checkout master
git fetch upstream/master
git merge upstream/master
git checkout <my-feature-branch>
git rebase master
git push --force

After rebasing, you may have merge conflicts, if you have made changes to code that has also changed in the main Cadasta/cadasta-platform repository. You need to resolve those conflicts before you can make a PR.

Once your topic branch is on GitHub, is up to date with the master branch of Cadasta/cadasta-platform, and all tests pass locally (you can run all tests using the tox command inside the development VM), then you can press the "Create pull request" button in GitHub. At this point, you should fill in the form describing your PR. Once you're done, the PR will be created and tests will be run on the Travis CI system. The test results should be identical to what you get by running tests locally using tox, so there should be no surprises.
Cadasta development team members will review your PR. They may have suggestions for changes that are needed before the PR can be merged. You can make those changes on your local PR branch and push them to GitHub where they will become part of the PR discussion thread. You may periodically need to update your PR branch to incorporate changes in the main Cadasta/cadasta-platform repo. GitHub tells you if this is necessary by adding a flag saying "This branch is out-of-date with the base branch" on the PR page. Just follow the procedure in #6 above to update your branch.
When the dev team is happy with your PR, they'll merge it!