mirror of
https://github.com/jimeh/commonflow.org.git
synced 2026-02-19 05:46:40 +00:00
Jim Myhrberg
cd659d7b4f
SVG diagrams use hardcoded black text that doesn't render correctly on dark backgrounds. Simplified to light theme only. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
196 lines
15 KiB
HTML
196 lines
15 KiB
HTML
<!DOCTYPE html><html lang="en" data-astro-cid-jwirc66j> <head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><link rel="canonical" href="https://commonflow.org/spec/1.0.0-rc.1/"><title>Git Common-Flow 1.0.0-rc.1 | Git Common Flow</title><meta name="description" content="An attempt to gather a sensible selection of the most common usage patterns of git into a single and concise specification."><meta name="author" content="Jim Myhrberg"><!-- Open Graph --><meta property="og:title" content="Git Common-Flow 1.0.0-rc.1 | Git Common Flow"><meta property="og:description" content="An attempt to gather a sensible selection of the most common usage patterns of git into a single and concise specification."><meta property="og:type" content="website"><meta property="og:url" content="https://commonflow.org/spec/1.0.0-rc.1/"><!-- Twitter --><meta name="twitter:card" content="summary"><meta name="twitter:title" content="Git Common-Flow 1.0.0-rc.1 | Git Common Flow"><meta name="twitter:description" content="An attempt to gather a sensible selection of the most common usage patterns of git into a single and concise specification."><!-- Fonts --><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Open+Sans+Condensed:wght@300;700&family=Open+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet"><link rel="stylesheet" href="/_astro/index.BMC0NJ9O.css"></head> <body data-astro-cid-jwirc66j> <div id="layout" data-astro-cid-jwirc66j> <a href="#menu" id="menuLink" class="menu-link" data-astro-cid-jyixok4n> <span data-astro-cid-jyixok4n></span> </a> <script type="module">function c(){const e=document.getElementById("layout"),n=document.getElementById("menu"),t=document.getElementById("menuLink"),s=document.getElementById("main");function i(o){o.preventDefault(),e?.classList.toggle("active"),n?.classList.toggle("active"),t?.classList.toggle("active")}function a(){e?.classList.remove("active"),n?.classList.remove("active"),t?.classList.remove("active")}t?.addEventListener("click",i),s?.addEventListener("click",()=>{e?.classList.contains("active")&&a()})}c();document.addEventListener("astro:after-swap",c);</script> <div id="menu" data-astro-cid-ssfzsv2f> <div class="menu-inner" data-astro-cid-ssfzsv2f> <ul class="menu-list" data-astro-cid-ssfzsv2f> <li class="menu-label" data-astro-cid-ssfzsv2f>Versions:</li> <li class="menu-item" data-astro-cid-ssfzsv2f> <a href="/spec/1.0.0-rc.5" class="menu-link-item" data-astro-cid-ssfzsv2f> 1.0.0-rc.5 </a> </li><li class="menu-item" data-astro-cid-ssfzsv2f> <a href="/spec/1.0.0-rc.4" class="menu-link-item" data-astro-cid-ssfzsv2f> 1.0.0-rc.4 </a> </li><li class="menu-item" data-astro-cid-ssfzsv2f> <a href="/spec/1.0.0-rc.3" class="menu-link-item" data-astro-cid-ssfzsv2f> 1.0.0-rc.3 </a> </li><li class="menu-item" data-astro-cid-ssfzsv2f> <a href="/spec/1.0.0-rc.2" class="menu-link-item" data-astro-cid-ssfzsv2f> 1.0.0-rc.2 </a> </li><li class="menu-item selected" data-astro-cid-ssfzsv2f> <a href="/spec/1.0.0-rc.1" class="menu-link-item" data-astro-cid-ssfzsv2f> 1.0.0-rc.1 </a> </li> </ul> </div> <div class="links" data-astro-cid-ssfzsv2f> <a href="https://github.com/jimeh/common-flow" aria-label="View on GitHub" class="github-link" data-astro-cid-ssfzsv2f> <svg class="w-12 h-12" fill="currentColor" viewBox="0 0 24 24" aria-hidden="true" data-astro-cid-ssfzsv2f> <path fill-rule="evenodd" d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839
|
||
9.504.5.092.682-.217.682-.483
|
||
0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608
|
||
1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088
|
||
2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951
|
||
0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65
|
||
0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004
|
||
1.705.115 2.504.337 1.909-1.296 2.747-1.027 2.747-1.027.546
|
||
1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028
|
||
2.688 0 3.848-2.339 4.695-4.566
|
||
4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012
|
||
2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22
|
||
6.484 17.522 2 12 2z" clip-rule="evenodd" data-astro-cid-ssfzsv2f></path> </svg> </a> </div> </div> <div id="main" data-astro-cid-jwirc66j> <div class="content" data-astro-cid-jwirc66j> <article class="spec-content"> <h1 id="git-common-flow-100-rc1">Git Common-Flow 1.0.0-rc.1</h1>
|
||
<img src="/spec/1.0.0-rc.1.svg" alt="Git Common-Flow 1.0.0-rc.1 diagram" width="100%">
|
||
<h2 id="summary">Summary</h2>
|
||
<p>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 <a href="http://scottchacon.com/2011/08/31/github-flow.html">original variant</a>
|
||
of <a href="https://guides.github.com/introduction/flow/">GitHub Flow</a>, while taking
|
||
into account how a lot of open source projects use git.</p>
|
||
<p>TL;DR: Common-Flow is basically GitHub Flow with the addition of versioned
|
||
releases, maintenance releases for old versions, and without the requirement to
|
||
deploy to production all the time.</p>
|
||
<h2 id="terminology">Terminology</h2>
|
||
<ul>
|
||
<li><strong>Master Branch</strong> - Must always have passing tests, is considered bleeding
|
||
edge, and must be named <code>master</code>.</li>
|
||
<li><strong>Change Branches</strong> - Any branch that introduces changes like a new feature, a
|
||
bug fix, etc.</li>
|
||
<li><strong>Source Branch</strong> - The branch that a change branch was created from. New
|
||
changes in the source branch should be incorporated into the change branch via
|
||
rebasing.</li>
|
||
<li><strong>Merge Target</strong> - 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.</li>
|
||
<li><strong>Maintenance Branches</strong> - Used for maintaining old versions and releasing
|
||
PATCH updates when the master branch has moved on. Should follow a
|
||
<code>stable-X.Y</code> naming pattern, where <code>X</code> is MAJOR version and <code>Y</code> is MINOR
|
||
version.</li>
|
||
<li><strong>Pull Request</strong> - A means of requesting that a change branch is merged in to
|
||
its merge target, allowing others to review, discuss and approve the changes.</li>
|
||
<li><strong>Release</strong> - Consists of a version bump commit directly on the master branch,
|
||
and a git tag named according to the new version string placed on said commit.</li>
|
||
<li><strong>Maintenance Release</strong> - Just like a regular release, except the version bump
|
||
commit and release tag are on a maintenance branch instead of the master
|
||
branch.</li>
|
||
</ul>
|
||
<h2 id="git-common-flow-specification-common-flow">Git Common-Flow Specification (Common-Flow)</h2>
|
||
<p>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 <a href="https://tools.ietf.org/html/rfc2119">RFC 2119</a>.</p>
|
||
<ol>
|
||
<li>The Master Branch
|
||
<ol>
|
||
<li>A branch named “master” MUST exist and it MUST be referred to as the
|
||
“master branch”.</li>
|
||
<li>The master branch MUST be considered bleeding edge.</li>
|
||
<li>The master branch MUST always be in a non-broken state with its test
|
||
suite passing.</li>
|
||
<li>The master branch SHOULD always be in a “as near as possible ready for
|
||
release/production” state to reduce the friction of creating a new
|
||
release.</li>
|
||
</ol>
|
||
</li>
|
||
<li>Changes
|
||
<ol>
|
||
<li>Changes MUST be performed on a separate branch that SHOULD be referred to
|
||
as a “change branch”. 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.</li>
|
||
<li>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.</li>
|
||
<li>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. To be clear you MUST NOT merge a source branch into a
|
||
change branch.</li>
|
||
<li>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 do a force
|
||
push, and you SHOULD use the “—force-with-lease” git push option.</li>
|
||
<li>To merge a change branch into its merge target branch, you MUST open a
|
||
“pull request” (or equivalent) so others can review and approve your
|
||
changes.</li>
|
||
<li>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.</li>
|
||
<li>To get feedback, help, or generally just discuss a change branch with
|
||
others, it is RECOMMENDED you do this by creating a pull request and
|
||
discuss the changes with others there.</li>
|
||
</ol>
|
||
</li>
|
||
<li>Git Best Practices
|
||
<ol>
|
||
<li>All commit messages SHOULD follow the Commit Guidelines and format from
|
||
the official git
|
||
documentation:
|
||
<a href="https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project">https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project</a></li>
|
||
<li>You SHOULD always use “—force-with-lease” when doing a force push. The
|
||
plain “—force” option is dangerous and destructive. More
|
||
information:
|
||
<a href="https://developer.atlassian.com/blog/2015/04/force-with-lease/">https://developer.atlassian.com/blog/2015/04/force-with-lease/</a></li>
|
||
<li>You SHOULD understand and be comfortable with
|
||
rebasing: <a href="https://git-scm.com/book/en/v2/Git-Branching-Rebasing">https://git-scm.com/book/en/v2/Git-Branching-Rebasing</a></li>
|
||
<li>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”.</li>
|
||
<li>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.</li>
|
||
</ol>
|
||
</li>
|
||
<li>Versioning
|
||
<ol>
|
||
<li>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.</li>
|
||
<li>If you are using a “VERSION” file in the root of the project, this MUST
|
||
only contain the exact version string.</li>
|
||
<li>The version string SHOULD follow the Semantic Versioning
|
||
(<a href="http://semver.org/">http://semver.org/</a>) 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.</li>
|
||
</ol>
|
||
</li>
|
||
<li>Releases
|
||
<ol>
|
||
<li>To create a new release, you MUST create a “version bump” commit directly
|
||
on the master branch which changes the hard-coded version value of the
|
||
project. The version bump commit MUST have a git tag created on it and
|
||
named as the exact version string.</li>
|
||
<li>A 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”</li>
|
||
<li>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”.</li>
|
||
<li>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.</li>
|
||
<li>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.</li>
|
||
</ol>
|
||
</li>
|
||
<li>Bug Fixes & Rollback
|
||
<ol>
|
||
<li>You MUST NOT under any circumstances force push to the master branch.</li>
|
||
<li>If a change branch which has been merged in to 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.</li>
|
||
<li>If a change branch is wrongfully merged in to 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.</li>
|
||
</ol>
|
||
</li>
|
||
<li>Maintenance Releases
|
||
<ol>
|
||
<li>Any branch that has a name starting with “stable-” SHOULD be referred to
|
||
as a “maintenance branch”.</li>
|
||
<li>Maintenance branches are used for managing new releases of older
|
||
versions. Typically this is used to provide security updates for older
|
||
versions when the master branch has moved on to a point that a new
|
||
release for the old version cannot be made from the master branch.</li>
|
||
<li>A “maintenance release” is identical to a regular release, except the
|
||
version bump commit and the release tag are placed on the maintenance
|
||
branch instead of on the master branch.</li>
|
||
<li>A maintenance branch SHOULD follow a “stable-X.Y” naming pattern, where
|
||
“X” is the MAJOR version and “Y” is the minor version.</li>
|
||
<li>A maintenance branch MUST be created from the relevant release tag. For
|
||
example if there is a security fix for all 2.9.x releases, the latest of
|
||
which is “2.9.7”, we create a new branch called “stable-2.9” off of the
|
||
“2.9.7” release tag. The security fix release will then end up being
|
||
version “2.9.8”.</li>
|
||
<li>When working on a maintenance release, the relevant maintenance branch
|
||
MUST be thought of as the master branch for that maintenance work.</li>
|
||
<li>Changes in a maintenance 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.</li>
|
||
</ol>
|
||
</li>
|
||
</ol>
|
||
<h2 id="about">About</h2>
|
||
<p>The Git Common-Flow specification is authored
|
||
by <a href="http://jimeh.me">Jim Myhrberg</a>.</p>
|
||
<p>If you’d like to leave feedback,
|
||
please <a href="https://github.com/jimeh/common-flow/issues">open an issue on GitHub</a>.</p>
|
||
<h2 id="license">License</h2>
|
||
<p><a href="http://creativecommons.org/licenses/by/3.0/">Creative Commons - CC BY 3.0</a></p> </article> </div> </div> </div> </body></html> |