Branching Strategy

MicroEngine follows a simplified Git Branching Model at its core, and the Shared Repository Model on GitHub, using Pull Requests.

There are two kinds of branches in use:

1. Persitent:
   1. Exist throughout the project's lifetime
   2. Amending/rebasing commits is forbidden: must never rewrite history
   3. Usually update via Pull Requests from other branches
2. Transient:
   1. Exist for short durations of time, eventually to be merged into a persistent branch
   2. Amending/rebasing is permitted on user branches

Note: Rewriting history means amending / rebasing / resetting commits (such that origin/{branch} and {branch} end up with diverged histories).

New changes are organised into user branches and kept up to date with origin/master throughout their lifetime. Once completed, they are merged (fast-forwarded) into origin/master via a Pull Request.

Branch Constraints

1. origin/master (Persistent): The default public state of the repository
   • Must be stable (code builds and runs on all supported environments)
   • Never pushed to (except by administrators)
   • Used by: everyone
2. Shared branches: origin/shared-<name> (and origin/dev) (Persistent):
   • Must be up-to-date with master
   • Should be stable
   • Updates via merges with master and user/feature branches
   • Used by: Collaborators, contributors
3. User branches (Transient): Individual branches for development / testing / prototyping / etc
   • Should always be up to update with master
   • Should minimise commit count before merging back into master
   • Rewriting history is encouraged when aiding in the above
   • Updates: master => {branch} can be rebased, but {branch} => master must be fast-forwarded via a PR
   • Create them via git branch {username}/{branch-name}; that will group them into "directories" in GUI clients
   • Used by: Individual collaborators
4. Feature branches (Transient): Individual long-running features, potentially collaborated upon
   • Must have a corresponding Issue being tracked
   • Should always be up to update with master
   • Should avoid rewriting history
   • Used by: Individual / multiple collaborators
5. Hotfix branches (Transient): Urgent fixes that are inteded to be merged into master
   • Must have a corresponding Issue being tracked
   • Must have as few commits as possible
   • Must merge back into master as soon as possible (via a Pull Request)
   • Used by: Collaborators

Pull Requests

For more information visit this page.

Creating Pull Requests:

1. git checkout master and ensure working directory is clean
2. Create a new user branch: {username}/awesome-feature
3. Commit, amend (not the root commit), rebase (on master), push (to origin/{username}/awesome-feature), etc
4. When ready:
   1. Ensure branch is up-to-date with origin/master; merge/rebase if not and resolve all conflicts
   2. Ensure user code is warning-free
   3. Run Tools/clang-format.sh -r
   4. Go to GitHub.com and select "New pull request"
   5. Pick base:master and compare:{username}/awesome-feature
   6. Add a meaningful description to the PR (include "close #{Issue}" if applicable)
   7. Select a reviewer and wait for them to review your changes
      1. If they request changes, make them and push another commit (on the same branch, and don't rewrite history any more!)
      2. Otherwise click "Merge" on the Pull Request
   8. Pull the latest in to your local master, and fast-forward your branch to the merged commit (and delete the branch if required)

Reviewing Pull Requests (to origin/master):

1. Ensure the target branch is master and the compare branch is up-to-date with it
2. Ensure linked issue (if present) is correct (and add/edit if necessary)
3. Ensure all configured status checks pass (build, build_release, etc), if any
4. Checkout the compare branch ({username}/awesome-feature)
5. Ensure changes conform to standards and respect .editorconfig
6. Ensure the build passes on all environments you have locally configured
7. Ensure the executable does not crash under any obvious conditions
8. Run Tools/clang-format.sh -r and ensure there are no changes
9. Take a decision:
   1. If all is good, select "Approve"
   2. Otherwise add comments for the PR author and select "Request changes"
10. Click "Submit Review"