Branching model

• We work with a single main branch and issue branches.
• main must be stable and deliverable at all times
• Deliveries are simple annotated tags on the main branch.
• Changes are made on issue branches and submitted for review and status checks via pull requests (PR).
• Nightlies are delivered on the main branch.
• The history is kept flat by squash-merging PRs when done.

Feature workflow

Here is the workflow followed by a GitHub issue, from its creation in the backlog to its integration into the main branch:

1. From a draft entry in the backlog create a new issue on the appropriate repository.
2. Use the Create a branch feature available from the issue page to create the associated feature branch.
3. Fetch the branch locally and do the work.
4. Once done rebase the branch, push it and open a corresponding PR from the GitHub website. This triggers automatic status checks.
5. Once the PR has been reviewed and all status checks pass submit the pull request to the merge queue.

Remark: You can open a PR before the work is finished if you want. Just ensure it is set to draft, which ensures that status checks are not made on-commit. Once ready for review simply set its status to reviewable and the status checks will be triggered automatically. When a PR is in draft you can still trigger status checks from TeamCity manually.

Spontaneous improvement / fix proposals

1. Create a local branch to do the work.
2. Once done rebase the branch, push it and open a corresponding PR.

Merging pull requests

After having reviewed a PR the original contributor is responsible to merge the changes back into the main branch:

1. Ensure the PR name is clean (should ideally start with an action verb, e.g. “Add AirPlay support”). The PR number will be automatically appended by GitHub.
2. Use Merge when ready on the PR page to add the PR to the merge queue.
3. If failures are encountered fix them (e.g. manual rebase) and repeat the process.