-
Git Common-Flow 1.0.0-rc.5
-
-
Introduction
-
Common-Flow is an attempt to gather a sensible selection of the most common
- usage patterns of git into a single and concise specification. It is based on
- the original variant
- of GitHub Flow, while taking
- into account how a lot of open source projects most commonly use git.
-
In short, Common-Flow is essentially GitHub Flow with the addition of versioned
- releases, optional release branches, and without the requirement to deploy to
- production all the time.
-
Summary
-
- - The "master" branch is the mainline branch with latest changes, and must not
- be broken.
- - Changes (features, bugfixes, etc.) are done on "change branches" created from
- the master branch.
- - Rebase change branches early and often.
- - When a change branch is stable and ready, it is merged back in to master.
- - A release is just a git tag who's name is the exact release version string
- (e.g. "2.11.4").
- - Release branches can be used to avoid change freezes on master. They are not
- required, instead they are available if you need them.
-
-
Terminology
-
- - Master Branch - Must be named "master", must always have passing tests,
- and is not guaranteed to always work in production environments.
- - Change Branches - Any branch that introduces changes like a new feature, a
- bug fix, etc.
- - Source Branch - The branch that a change branch was created from. New
- changes in the source branch should be incorporated into the change branch via
- rebasing.
- - Merge Target - A branch that is the intended merge target for a change
- branch. Typically the merge target branch will be the same as the source
- branch.
- - Pull Request - A means of requesting that a change branch is merged in to
- its merge target, allowing others to review, discuss and approve the changes.
- - Release - May be considered safe to use in production environments. Is
- effectively just a git tag named after the version of the release.
- - Release Branches - Used both for short-term preparations of a release, and
- also for long-term maintenance of older version.
-
-
Git Common-Flow Specification (Common-Flow)
-
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
- "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
- interpreted as described in RFC 2119.
-
- - TL;DR
-
- - Do not break the master branch.
- - A release is a git tag.
-
-
- - The Master Branch
-
- - A branch named "master" MUST exist and it MUST be referred to as the
- "master branch".
- - The master branch MUST always be in a non-broken state with its test
- suite passing.
- - The master branch IS NOT guaranteed to always work in production
- environments. Despite test suites passing it may at times contain
- unfinished work. Only releases may be considered safe for production use.
- - The master branch SHOULD always be in a "as near as possibly ready for
- release/production" state to reduce any friction with creating a new
- release.
-
-
- - Change Branches
-
- - Each change (feature, bugfix, etc.) MUST be performed on separate
- branches that SHOULD be referred to as "change branches".
- - All change branches MUST have descriptive names.
- - It is RECOMMENDED that you commit often locally, and that you try and
- keep the commits reasonably structured to avoid a messy and confusing git
- history.
- - You SHOULD regularly push your work to the same named branch on the
- remote server.
- - You SHOULD create separate change branches for each distinctly different
- change. You SHOULD NOT include multiple unrelated changes into a single
- change branch.
- - When a change branch is created, the branch that it is created from
- SHOULD be referred to as the "source branch". Each change branch also
- needs a designated "merge target" branch, typically this will be the same
- as the source branch.
- - Change branches MUST be regularly updated with any changes from their
- source branch. This MUST be done by rebasing the change branch on top of
- the source branch.
- - After updating a change branch from its source branch you MUST push the
- change branch to the remote server. Due to the nature of rebasing, you
- will be required to do a force push, and you MUST use the
- "--force-with-lease" git push option when doing so instead of the regular
- "--force".
- - If there is a truly valid technical reason to not use rebase when
- updating change branches, then you can update change branches via merge
- instead of rebase. The decision to use merge MUST only be taken after all
- possible options to use rebase have been tried and failed. People not
- understanding how to use rebase is NOT a valid reason to use merge. If
- you do decide to use merge instead of rebase, you MUST NOT use a mixture
- of both methods, pick one and stick to it.
-
-
- - Pull Requests
-
- - To merge a change branch into its merge target, you MUST open a "pull
- request" (or equivalent).
- - The purpose of a pull request is to allow others to review your changes
- and give feedback. You can then fix any issues, complaints, and more that
- might arise, and then let people review again.
- - Before creating a pull request, it is RECOMMENDED that you consider the
- state of your change branch's commit history. If it is messy and
- confusing, it might be a good idea to rebase your branch with "git rebase
- -i" to present a cleaner and easier to follow commit history for your
- reviewers.
- - A pull request MUST only be merged when the change branch is up-to-date
- with its source branch, the test suite is passing, and you and others are
- happy with the change. This is especially important if the merge target
- is the master branch.
- - To get feedback, help, or generally just discuss a change branch with
- others, it is RECOMMENDED you create a pull request and discuss the
- changes with others there. This leaves a clear and visible history of
- how, when, and why the code looks and behaves the way it does.
-
-
- - Versioning
-
- - A "version string" is a typically mostly numeric string that identifies a
- specific version of a project. The version string itself MUST NOT have a
- "v" prefix, but the version string can be displayed with a "v" prefix to
- indicate it is a version that is being referred to.
- - The source of truth for a project's version MUST be a git tag with a name
- based on the version string. This kind of tag MUST be referred to as a
- "release tag".
- - It is OPTIONAL, but RECOMMENDED to also keep the version string
- hard-coded somewhere in the project code-base.
- - If you hard-code the version string into the code-base, it is RECOMMENDED
- that you do so in a file called "VERSION" located in the root of the
- project. But be mindful of the conventions of your programming language
- and community when choosing if, where and how to hard-code the version
- string.
- - If you are using a "VERSION" file in the root of the project, this file
- MUST only contain the exact version string, meaning it MUST NOT have a
- "v" prefix. For example "v2.11.4" is bad, and "2.11.4" is good.
- - It is OPTIONAL, but RECOMMENDED that that the version string follows
- Semantic Versioning (http://semver.org/).
-
-
- - Releases
-
- - To create a new release, you MUST create a git tag named as the exact
- version string of the release. This kind of tag MUST be referred to as a
- "release tag".
- - The release tag name can OPTIONALLY be prefixed with "v". For example the
- tag name can be either "2.11.4" or "v2.11.4". It is however RECOMMENDED
- that you do not use a "v" prefix. You MUST NOT use a mixture of "v"
- prefixed and non-prefixed tags. Pick one form and stick to it.
- - If the version string is hard-coded into the code-base, you MUST create a
- "version bump" commit which changes the hard-coded version string of the
- project.
- - When using version bump commits, the release tag MUST be placed on the
- version bump commit.
- - If you are not using a release branch, then the release tag, and if
- relevant the version bump commit, MUST be created directly on the master
- branch.
- - The version bump commit SHOULD have a commit message title of "Bump
- version to VERSION". For example, if the new version string is "2.11.4",
- the first line of the commit message SHOULD read: "Bump version to
- 2.11.4"
- - It is RECOMMENDED that release tags are lightweight tags, but you can
- OPTIONALLY use annotated tags if you want to include changelog
- information in the release tag itself.
- - If you use annotated release tags, the first line of the annotation
- SHOULD read "Release VERSION". For example for version "2.11.4" the first
- line of the tag annotation SHOULD read "Release 2.11.4". The second line
- MUST be blank, and the changelog MUST start on the third line.
-
-
- - Short-Term Release Branches
-
- - Any branch that has a name starting with "release-" SHOULD be referred to
- as a "release branch".
- - Any release branch which has a name ending with a specific version
- string, MUST be referred to as a "short-term release branch".
- - Use of short-term release branches are OPTIONAL, and intended to be used
- to create a specific versioned release.
- - A short-term release branch is RECOMMENDED if there is a lengthy
- pre-release verification process to avoid a code freeze on the master
- branch.
- - Short-term release branches MUST have a name of "release-VERSION". For
- example for version "2.11.4" the release branch name MUST be
- "release-2.11.4".
- - When using a short-term release branch to create a release, the release
- tag and if used, version bump commit, MUST be placed directly on the
- short-term release branch itself.
- - Only very minor changes should be performed on a short-term release
- branch directly. Any larger changes SHOULD be done in the master branch,
- and SHOULD be pulled into the release branch by rebasing it on top of the
- master branch the same way a change branch pulls in updates from its
- source branch.
- - After a release tag has been created, the release branch MUST be merged
- back into its source branch and then deleted. Typically the source branch
- will be the master branch.
-
-
- - Long-term Release Branches
-
- - Any release branch which has a name ending with a non-specific version
- string, MUST be referred to as a "long-term release branch". For example
- "release-2.11" is a long-term release branch, while "release-2.11.4" is a
- short-term release branch.
- - Use of long-term release branches are OPTIONAL, and intended for work on
- versions which are not currently part of the master branch. Typically
- this is useful when you need to create a new maintenance release for a
- older version.
- - A long-term release branch MUST have a name with a non-specific version
- number. For example a long-term release branch for creating new 2.9.x
- releases MUST be named "release-2.9".
- - Long-term release branches for maintenance releases of older versions
- MUST be created from the relevant release tag. For example if the master
- branch is on version 2.11.4 and there is a security fix for all 2.9.x
- releases, the latest of which is "2.9.7". Create a new branch called
- "release-2.9" from the "2.9.7" release tag. The security fix release will
- then end up being version "2.9.8".
- - To create a new release from a long-term release branch, you MUST follow
- the same process as a release from the master branch, except the
- long-term release branch takes the place of the master branch.
- - A long-term release branch should be treated with the same respect as the
- master branch. It is effectively the master branch for the release series
- in question. Meaning it MUST always be in a non-broken state, MUST NOT be
- force pushed to, etc.
-
-
- - Bug Fixes & Rollback
-
- - You MUST NOT under any circumstances force push to the master branch or
- to long-term release branches.
- - If a change branch which has been merged into the master branch is found
- to have a bug in it, the bug fix work MUST be done as a new separate
- change branch and MUST follow the same workflow as any other change
- branch.
- - If a change branch is wrongfully merged into master, or for any other
- reason the merge must be undone, you MUST undo the merge by reverting the
- merge commit itself. Effectively creating a new commit that reverses all
- the relevant changes.
-
-
- - Git Best Practices
-
- - All commit messages SHOULD follow the Commit Guidelines and format from
- the official git
- documentation:
- https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines
- - You SHOULD never blindly commit all changes with "git commit -a". It is
- RECOMMENDED you use "git add -i" or "git add -p" to add individual
- changes to the staging area so you are fully aware of what you are
- committing.
- - You SHOULD always use "--force-with-lease" when doing a force push. The
- regular "--force" option is dangerous and destructive. More
- information:
- https://developer.atlassian.com/blog/2015/04/force-with-lease/
- - You SHOULD understand and be comfortable with
- rebasing: https://git-scm.com/book/en/v2/Git-Branching-Rebasing
- - It is RECOMMENDED that you always do "git pull --rebase" instead of "git
- pull" to avoid unnecessary merge commits. You can make this the default
- behavior of "git pull" with "git config --global pull.rebase true".
- - It is RECOMMENDED that all branches be merged using "git merge --no-ff".
- This makes sure the reference to the original branch is kept in the
- commits, allows one to revert a merge by reverting a single merge commit,
- and creates a merge commit to mark the integration of the branch with
- master.
-
-
-
-
FAQ
-
Why use Common-Flow instead of Git Flow, and how does it differ?
-
Common-Flow tries to be a lot less complicated than Git Flow by having fewer
- types of branches, and simpler rules. Normal day to day development doesn't
- really change much:
-
- - You create change branches instead of feature branches, without the need of a
- "feature/" or "change/" prefix in the branch name.
- - Change branches are typically created from and merged back into "master"
- instead of "develop".
- - Creating a release is done by simply creating a git tag, typically on the
- master branch.
-
-
In detail, the main differences between Git Flow and Common-Flow are:
-
- - There is no "develop" branch, there is only a "master" branch which contains
- the latest work. In Git Flow the master branch effectively ends up just being
- a pointer to the latest release, despite the fact that Git Flow includes
- release tags too. In Common-Flow you just look at the tags to find the latest
- release.
- - There are no "feature" or "hotfix" branches, there's only "change"
- branches. Any branch that is not master and introduces changes is a change
- branch. Change branches also don't have a enforced naming convention, they
- just have to have a "descriptive name". This makes things simpler and allows
- more flexibility.
- - Release branches are available, but optional. Instead of enforcing the use of
- release branches like Git Flow, Common-Flow only recommends the use of release
- branches when it makes things easier. If creating a new release by tagging
- "master" works for you, great, do that.
-
-
Why use Common-Flow instead of GitHub Flow, and how does it differ?
-
Common-Flow is essentially GitHub Flow with the addition of a "Release" concept
- that uses tags. It also attempts to define how certain common tasks are done,
- like updating change/feature branches from their source branches for
- example. This is to help end arguments about how such things are done.
-
If a deployment/release for you is just getting the latest code in the master
- branch out, without caring about bumping version numbers or anything, then
- GitHub Flow is a good fit for you, and you probably don't need the extras of
- Common-Flow.
-
However if your deployments/releases have specific version numbers, then
- Common-Flow gives you a simple set of rules of how to create and manage
- releases, on top of what GitHub Flow already does.
-
What does "descriptive name" mean for change branches?
-
It means what it sounds like. The name should be descriptive, as in by just
- reading the name of the branch you should understand what the branch's purpose
- is and what it does. Here's a few examples:
-
- - add-2fa-support
- - fix-login-issue
- - remove-sort-by-middle-name-functionality
- - update-font-awesome
- - change-search-behavior
- - improve-pagination-performance
- - tweak-footer-style
-
-
Notice how none of these have any prefixes like "feature/" or "hotfix/", they're
- not needed when branch names are properly descriptive. However there's nothing
- to say you can't use such prefixes if you want.
-
You can also add ticket numbers to the branch name if your team/org has that as
- part of it's process. But it is recommended that ticket numbers are added to the
- end of the branch name. The ticket number is essentially metadata, so put it at
- the end and out of the way of humans trying to read the descriptive name from
- left to right.
-
How do we release an emergency hotfix when the master branch is broken?
-
This should ideally never happen, however if it does you can do one of the
- following:
-
- - Review why the master branch is broken and revert the changes that caused the
- issues. Then apply the hotfix and release.
- - Or use a short-term release branch created from the latest release tag instead
- of the master branch. Apply the hotfix to the release branch, create a release
- tag on the release branch, and then merge it back into master.
-
-
In this situation, it is recommended you try to revert the offending changes
- that's preventing a new release from master. But if that proves to be a
- complicated task and you're short on time, a short-term release branch gives you
- a instant fix to the situation at hand, and let's you resolve the issues with
- the master branch when you have more time on your hands.
-
About
-
The Git Common-Flow specification is authored
- by Jim Myhrberg.
-
If you'd like to leave feedback,
- please open an issue on GitHub.
-
License
-
Creative Commons - CC BY 4.0
-
+
