jimeh/common-flow
1
0
Fork 0
mirror of https://github.com/jimeh/common-flow.git synced 2026-02-19 09:26:40 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #26 from jimeh/update-branch-terminology

Browse Source
This commit is contained in:
Jim Myhrberg
2026-01-10 06:54:29 +00:00
committed by GitHub
parent be5f5dd71b 613f707ffe
commit 12daa305b3
1 changed files with 41 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
common-flow.md
View File

@@ -17,21 +17,21 @@ production all the time.
Summary
-------
- The "master" branch is the mainline branch with latest changes, and must not
- The "main" 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.
the main branch.
- Rebase change branches [early and often](https://i.imgur.com/1RS8x2d.png).
- When a change branch is stable and ready, it is merged back in to master.
- When a change branch is stable and ready, it is merged back in to main.
- 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
- Release branches can be used to avoid change freezes on main. They are not
required, instead they are available if you need them.
Terminology
-----------
- **Master Branch** - Must be named "master", must always have passing tests,
- **Main Branch** - Must be named "main", 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.
@@ -56,17 +56,17 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
1. TL;DR
1. Do not break the master branch.
1. Do not break the main 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
2. The Main Branch
1. A branch named "main" MUST exist and it MUST be referred to as the
"main branch".
2. The main 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
3. The main 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
4. The main 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
@@ -114,7 +114,7 @@ interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
4. 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.
is the main branch.
5. 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
@@ -153,7 +153,7 @@ interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
4. When using version bump commits, the release tag MUST be placed on the
version bump commit.
5. 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
relevant the version bump commit, MUST be created directly on the main
branch.
6. 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",
@@ -174,7 +174,7 @@ interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
3. Use of short-term release branches are OPTIONAL, and intended to be used
to create a specific versioned release.
4. A short-term release branch is RECOMMENDED if there is a lengthy
pre-release verification process to avoid a code freeze on the master
pre-release verification process to avoid a code freeze on the main
branch.
5. Short-term release branches MUST have a name of "release-VERSION". For
example for version "2.11.4" the release branch name MUST be
@@ -183,46 +183,46 @@ interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
tag and if used, version bump commit, MUST be placed directly on the
short-term release branch itself.
7. Only very minor changes should be performed on a short-term release
branch directly. Any larger changes SHOULD be done in the master branch,
branch directly. Any larger changes SHOULD be done in the main 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
main branch the same way a change branch pulls in updates from its
source branch.
8. 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.
will be the main branch.
8. Long-term Release Branches
1. 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.
2. Use of long-term release branches are OPTIONAL, and intended for work on
versions which are not currently part of the master branch. Typically
versions which are not currently part of the main branch. Typically
this is useful when you need to create a new maintenance release for a
older version.
3. 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".
4. Long-term release branches for maintenance releases of older versions
MUST be created from the relevant release tag. For example if the master
MUST be created from the relevant release tag. For example if the main
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".
5. 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.
7. 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
the same process as a release from the main branch, except the
long-term release branch takes the place of the main branch.
6. A long-term release branch should be treated with the same respect as the
main branch. It is effectively the main branch for the release series
in question. Meaning it MUST always be in a non-broken state, MUST NOT be
force pushed to, etc.
9. Bug Fixes & Rollback
1. You MUST NOT under any circumstances force push to the master branch or
1. You MUST NOT under any circumstances force push to the main branch or
to long-term release branches.
2. If a change branch which has been merged into the master branch is found
2. If a change branch which has been merged into the main 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
3. If a change branch is wrongfully merged into main, 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.
@@ -248,7 +248,7 @@ interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
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.
main.
FAQ
---
@@ -261,27 +261,27 @@ 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"
- Change branches are typically created from and merged back into "main"
instead of "develop".
- Creating a release is done by simply creating a git tag, typically on the
master branch.
main 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
- There is no "develop" branch, there is only a "main" branch which contains
the latest work. In Git Flow the main 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
branches. Any branch that is not main 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.
"main" works for you, great, do that.
### Why use Common-Flow instead of GitHub Flow, and how does it differ?
@@ -290,7 +290,7 @@ 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
If a deployment/release for you is just getting the latest code in the main
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.
@@ -323,22 +323,22 @@ 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?
### How do we release an emergency hotfix when the main 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
- Review why the main 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.
of the main branch. Apply the hotfix to the release branch, create a release
tag on the release branch, and then merge it back into main.
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
that's preventing a new release from main. 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.
the main branch when you have more time on your hands.
About
-----