Branching Strategy

Chronos internal projects will follow the Gitflow pattern for branching. Gitflow is the standard for all new projects.

Branching Models

Gitflow

Gitflow is a branching model that organizes a repository into distinct branches, each with a unique purpose. It facilitates the ability to generate quality software via a stable release and development process.

Diagram created by Vincent Driessen

Branches

master

• Each commit in master should reflect a stable release and be tagged with that release's version number.
• The latest commit in master reflects the build currently available in the App Store.
• Until the first version of the app is released, master will usually reflect the initial state of the repository.

develop

• The main development branch, which reflects the most current non-shipped version of the app.
• Serves as the main integration point for new features/fixes as they are developed.
• The CI system points to develop by default.

feature/*

• Represents a feature actively in development (e.g. feature/login_screen).
• Initially branched from develop to start feature work.
• As the feature is developed, develop should be merged into feature/* periodically to keep the feature branch up-to-date with the latest changes.
• Once the feature is complete, the feature/* branch is merged into develop (via pull request) and then removed.

release/*

• Represents a release candidate (e.g. release/2.1.0).
• Initially branched from develop to start a code freeze process.
  • Only bugfixes should be merged into the release/ branch (i.e. no merging from feature/ branches).
• Merged into develop periodically so that fixes get incorporated into new feature development.
• Merged into master and tagged using semantic versioning once a release is complete (i.e. the app/update is live).
• Merged into develop one last time before being removed.
• QA will perform the bulk of their testing on builds created from this branch.

hotfix/*

• Represents a "hotfix" update used to quickly address issues with the live app.
• Initially created from the corresponding version number tag on the master branch (e.g. 2.1.0 --> hotfix/2.1.1).
• Allows for production issues to be resolved quickly without interrupting active feature development or having to manually cherry-pick or re-apply fixes from develop.
• Follows the same process as a release/* branch to keep develop up-to-date with any fixes and finalize the hotfix release.

bugfix/*

• Represents a bugfix actively in development (e.g. bugfix/login_screen).
• Initially branched from develop to start the bugfix work.
• As the bugfix is developed, develop should be merged into bugfix/* periodically to keep the bugfix branch up-to-date with the latest changes.
• Once the bugfix is complete, the bugfix/* branch is merged into develop (via pull request) and then removed.

Key Stages

1. The repo is created with only a master branch, by default.
2. A develop branch is created from master.
3. feature/* branches are created from develop.
4. When a feature is complete, it's merged into develop (via PR) and then removed.
5. To initiate a release, a release/* branch is created from develop.
6. When a release is complete, release/* is merged into develop and master, tagged, and then removed.
7. If an issue in master needs to be resolved, a hotfix/* branch is created from master.
8. When the hotfix release is complete, hotfix/* is merged into develop and master, tagged, and then removed.

Commits

Commit early, commit often! Try to remember to push any pending commits to the remote repo at the end of every day so that all in-progress work is backed up.

Commit messages should be detailed and helpful - avoid anything that's not a complete sentence.. A good rule of thumb to follow is to begin commit messages with a verb so that the message completes the phrase "This commit...".

Merging

All merges into develop, release/, hotfix/, bugfix/* should happen via pull requests. This ensures that all code gets reviewed at some point before it's shipped.

Deleting Branches

Branches should be deleted after they've been merged into develop or master. This keeps the repository clean and makes it clear where active development is occurring.