mirror of
https://github.com/jimeh/common-flow.git
synced 2026-02-19 09:26:40 +00:00
209 lines
12 KiB
Markdown
209 lines
12 KiB
Markdown
Git Common-Flow {{version}}
|
|
===========================
|
|
|
|
Summary
|
|
-------
|
|
|
|
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](http://scottchacon.com/2011/08/31/github-flow.html)
|
|
of [GitHub Flow](https://guides.github.com/introduction/flow/), while taking
|
|
into account how a lot of open source projects 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.
|
|
|
|
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. Consists of a version bump commit, and a git tag named according
|
|
to the new version string placed on said commit.
|
|
- **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](https://tools.ietf.org/html/rfc2119).
|
|
|
|
1. TL;DR
|
|
1. Don't break the master branch.
|
|
2. A release is a git tag.
|
|
2. The Master Branch
|
|
1. A branch named "master" MUST exist and it MUST be referred to as the
|
|
"master branch".
|
|
2. The master branch MUST always be in a non-broken state with its test
|
|
suite passing.
|
|
4. 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.
|
|
5. 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.
|
|
3. Change Branches
|
|
1. 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 you SHOULD regularly push your work to the same named
|
|
branch on the remote server.
|
|
2. You MUST create separate change branches for each distinctly different
|
|
change. You MUST NOT include multiple unrelated changes into a single
|
|
change branch.
|
|
3. 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.
|
|
4. 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.
|
|
5. After rebasing a change branch on top of its source branch you MUST push
|
|
the change branch to the remote server. This will require you to do a
|
|
force push, and you SHOULD use the "--force-with-lease" git push option.
|
|
4. Pull Requests
|
|
1. To merge a change branch into its merge target, you MUST open a "pull
|
|
request" (or equivalent) so others can review and approve your changes.
|
|
2. 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.
|
|
3. To get feedback, help, or generally just discuss a change branch with
|
|
others, the RECOMMENDED way to do so is by creating a pull request and
|
|
discuss the changes with others there.
|
|
5. Versioning
|
|
1. The project MUST have its version hard-coded somewhere in the
|
|
code-base. It is RECOMMENDED that this is done in a file called "VERSION"
|
|
located in the root of the project.
|
|
2. If you are using a "VERSION" file in the root of the project, this MUST
|
|
only contain the exact version string.
|
|
3. The version string SHOULD follow the Semantic Versioning
|
|
(<http://semver.org/>) format. Use of Semantic Versioning is OPTIONAL,
|
|
but the version string MUST NOT have a "v" prefix. For example "v2.11.4"
|
|
is bad, and "2.11.4" is good.
|
|
6. Releases
|
|
1. To create a new release, you MUST create a "version bump" commit which
|
|
changes the hard-coded version string of the project. The version bump
|
|
commit MUST have a git tag created on it and named as the exact version
|
|
string.
|
|
2. If you are not using a release branch, then the version bump commit MUST
|
|
be created directly on the master branch.
|
|
3. The version bump commit MUST 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 MUST read: "Bump version to 2.11.4"
|
|
4. The release tag on the version bump commit MUST be named exactly the same
|
|
as the version string. The tag name can OPTIONALLY be prefixed with
|
|
"v". For example the tag name can be either "2.11.4" or "v2.11.4". You
|
|
MUST not use a mix of "v" prefixed and non-prefixed tags. Pick one form
|
|
and stick to it.
|
|
5. 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.
|
|
6. If you use annotated release tags, the first line of the annotation MUST
|
|
read "Release VERSION". For example for version "2.11.4" the first line
|
|
of the tag annotation would read "Release 2.11.4". The second line must
|
|
be blank, and the changelog MUST start on the third line.
|
|
7. Release Branches
|
|
1. Any branch that has a name starting with "release-" SHOULD be referred to
|
|
as a "release branch".
|
|
2. Use of release branches is OPTIONAL.
|
|
3. Changes in a release branch SHOULD typically come from work being
|
|
done against the master branch. Meaning changes SHOULD only trickle
|
|
downwards from the master branch. If a change needs to trickle back up
|
|
into the master branch, that work should have happened against the master
|
|
branch in the first place. One exception to this is version bump commits.
|
|
4. There are two types of release branches; short-term, and long-term.
|
|
5. Short-Term Release Branches
|
|
1. Used for creating a specific versioned release.
|
|
2. 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.
|
|
3. MUST have a name of "release-VERSION". For example for version
|
|
"2.11.4" the release branch name MUST be "release-2.11.4".
|
|
4. When using a short-term release branch, the version bump commit and
|
|
release tag MUST be made directly on the release branch itself.
|
|
5. 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.
|
|
6. After the version bump commit and release tag have 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.
|
|
6. Long-Term Release Branches
|
|
1. Used 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.
|
|
2. The branch name MUST have a non-specific version number. For example
|
|
a long-term release branch for creating new 2.9.x releases would be
|
|
named "release-2.9".
|
|
3. To create a new release from a long-term release branch, you MUST
|
|
create a version bump commit and release tag directly on the release
|
|
branch.
|
|
4. A long-term release branch 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" off of the "2.9.7"
|
|
release tag. The security fix release will then end up being version
|
|
"2.9.8".
|
|
8. Bug Fixes & Rollback
|
|
1. You MUST NOT under any circumstances force push to the master branch.
|
|
2. 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.
|
|
3. 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.
|
|
9. Git Best Practices
|
|
1. 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>
|
|
2. You SHOULD never blindly commit all changes with "git commit -a". It is
|
|
RECOMMENDED you use "git add -p" or "git add -i" to add individual changes to the staging
|
|
area so you are fully aware of what you are committing.
|
|
3. 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/>
|
|
4. You SHOULD understand and be comfortable with
|
|
rebasing: <https://git-scm.com/book/en/v2/Git-Branching-Rebasing>
|
|
5. 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".
|
|
6. 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.
|
|
|
|
About
|
|
-----
|
|
|
|
The Git Common-Flow specification is authored
|
|
by [Jim Myhrberg](http://jimeh.me).
|
|
|
|
If you'd like to leave feedback,
|
|
please [open an issue on GitHub](https://github.com/jimeh/common-flow/issues).
|
|
|
|
License
|
|
-------
|
|
|
|
[Creative Commons - CC BY 3.0](http://creativecommons.org/licenses/by/3.0/)
|