mirror of
https://github.com/jimeh/commonflow.org.git
synced 2026-02-19 05:46:40 +00:00
453 lines
59 KiB
HTML
453 lines
59 KiB
HTML
<!DOCTYPE html><html lang="en"> <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.2/raw/"><title>Git Common-Flow 1.0.0-rc.2 - Raw Markdown | 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.2 - Raw Markdown | 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.2/raw/"><!-- Twitter --><meta name="twitter:card" content="summary"><meta name="twitter:title" content="Git Common-Flow 1.0.0-rc.2 - Raw Markdown | 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."><!-- Favicon --><link rel="icon" href="/favicon.ico" sizes="32x32"><link rel="icon" href="/favicon.svg" type="image/svg+xml"><link rel="apple-touch-icon" href="/apple-touch-icon.png"><!-- Prevent flash of wrong theme --><script>
|
|
(function () {
|
|
const mode = localStorage.getItem("theme");
|
|
const prefersDark = window.matchMedia(
|
|
"(prefers-color-scheme: dark)",
|
|
).matches;
|
|
if (mode === "dark" || (mode !== "light" && prefersDark)) {
|
|
document.documentElement.classList.add("dark");
|
|
}
|
|
})();
|
|
</script><link rel="stylesheet" href="/_astro/index.D1CCjkm0.css">
|
|
<style>.dark .shiki{color:var(--shiki-dark)!important;background-color:var(--shiki-dark-bg)!important}.dark .shiki span{color:var(--shiki-dark)!important}
|
|
</style></head> <body class="min-h-screen"> <header class="sticky top-0 z-50 border-b
|
|
border-gray-200 dark:border-neutral-800
|
|
backdrop-blur-xl bg-gray-50/85 dark:bg-neutral-950/85"> <div class="max-w-6xl mx-auto px-4 sm:px-6 h-16 flex items-center
|
|
justify-between"> <!-- Back link and title --> <div class="flex items-center gap-4"> <a href="/spec/1.0.0-rc.2" class="inline-flex items-center gap-1.5 text-sm font-medium
|
|
text-gray-600 dark:text-neutral-400
|
|
hover:text-sky-600 dark:hover:text-sky-400 transition-colors"> <svg width="1em" height="1em" class="w-4 h-4" data-icon="heroicons:arrow-left"> <symbol id="ai:heroicons:arrow-left" viewBox="0 0 24 24"><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M10.5 19.5L3 12m0 0l7.5-7.5M3 12h18"/></symbol><use href="#ai:heroicons:arrow-left"></use> </svg> <span class="hidden sm:inline">Back to Spec</span> </a> <span class="hidden sm:inline text-gray-300 dark:text-neutral-700">|</span> <span class="font-display font-bold text-lg tracking-tight"> <span class="hidden sm:inline">Raw </span>Markdown
|
|
</span> <span class="hidden sm:inline-block px-2 py-0.5 text-xs font-semibold
|
|
rounded-full bg-sky-100 text-sky-700
|
|
dark:bg-sky-900/50 dark:text-sky-300">
|
|
v1.0.0-rc.2 </span> </div> <!-- Right side: Copy, Download, Theme, GitHub --> <div class="flex items-center gap-2"> <div class="relative"> <button id="copy-btn" type="button" class="inline-flex items-center gap-1.5 px-3 py-1.5 text-sm
|
|
font-medium rounded-lg transition-colors cursor-pointer
|
|
text-gray-600 dark:text-neutral-400
|
|
hover:bg-gray-100 hover:text-gray-950
|
|
dark:hover:bg-neutral-800 dark:hover:text-neutral-50"> <svg width="1em" height="1em" class="w-4 h-4" data-icon="heroicons:clipboard-document"> <symbol id="ai:heroicons:clipboard-document" viewBox="0 0 24 24"><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M8.25 7.5V6.108c0-1.135.845-2.098 1.976-2.192q.56-.045 1.124-.08M15.75 18H18a2.25 2.25 0 0 0 2.25-2.25V6.108c0-1.135-.845-2.098-1.976-2.192a48 48 0 0 0-1.123-.08M15.75 18.75v-1.875a3.375 3.375 0 0 0-3.375-3.375h-1.5a1.125 1.125 0 0 1-1.125-1.125v-1.5A3.375 3.375 0 0 0 6.375 7.5H5.25m11.9-3.664A2.25 2.25 0 0 0 15 2.25h-1.5a2.25 2.25 0 0 0-2.15 1.586m5.8 0q.099.316.1.664v.75h-6V4.5q.001-.348.1-.664M6.75 7.5H4.875c-.621 0-1.125.504-1.125 1.125v12c0 .621.504 1.125 1.125 1.125h9.75c.621 0 1.125-.504 1.125-1.125V16.5a9 9 0 0 0-9-9"/></symbol><use href="#ai:heroicons:clipboard-document"></use> </svg> <span class="hidden sm:inline" data-copy-text>Copy</span> </button> <!-- Mobile tooltip --> <div id="copy-tooltip" class="sm:hidden absolute left-1/2 -translate-x-1/2 top-full mt-2
|
|
px-2 py-1 text-xs font-medium whitespace-nowrap rounded-md
|
|
shadow-sm bg-gray-900 text-white dark:bg-white
|
|
dark:text-gray-900 opacity-0 pointer-events-none
|
|
transition-opacity duration-200">
|
|
Copied!
|
|
</div> </div> <button id="download-btn" type="button" class="inline-flex items-center gap-1.5 px-3 py-1.5 text-sm
|
|
font-medium rounded-lg transition-colors cursor-pointer
|
|
text-gray-600 dark:text-neutral-400
|
|
hover:bg-gray-100 hover:text-gray-950
|
|
dark:hover:bg-neutral-800 dark:hover:text-neutral-50" data-filename="common-flow-1.0.0-rc.2.md"> <svg width="1em" height="1em" class="w-4 h-4" data-icon="heroicons:arrow-down-tray"> <symbol id="ai:heroicons:arrow-down-tray" viewBox="0 0 24 24"><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M3 16.5v2.25A2.25 2.25 0 0 0 5.25 21h13.5A2.25 2.25 0 0 0 21 18.75V16.5M16.5 12L12 16.5m0 0L7.5 12m4.5 4.5V3"/></symbol><use href="#ai:heroicons:arrow-down-tray"></use> </svg> <span class="hidden sm:inline">Download</span> </button> <div class="relative group"> <button data-theme-toggle type="button" class="p-2 rounded-lg cursor-pointer transition-colors duration-200
|
|
text-gray-500 dark:text-neutral-500
|
|
hover:text-gray-950 dark:hover:text-neutral-50
|
|
hover:bg-gray-100 dark:hover:bg-neutral-800" aria-label="Toggle theme"> <svg width="1em" height="1em" data-theme-icon="light" class="hidden w-5 h-5" data-icon="heroicons:sun"> <symbol id="ai:heroicons:sun" viewBox="0 0 24 24"><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M12 3v2.25m6.364.386l-1.591 1.591M21 12h-2.25m-.386 6.364l-1.591-1.591M12 18.75V21m-4.773-4.227l-1.591 1.591M5.25 12H3m4.227-4.773L5.636 5.636M15.75 12a3.75 3.75 0 1 1-7.5 0a3.75 3.75 0 0 1 7.5 0"/></symbol><use href="#ai:heroicons:sun"></use> </svg> <svg width="1em" height="1em" data-theme-icon="dark" class="hidden w-5 h-5" data-icon="heroicons:moon"> <symbol id="ai:heroicons:moon" viewBox="0 0 24 24"><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M21.752 15.002A9.7 9.7 0 0 1 18 15.75A9.75 9.75 0 0 1 8.25 6c0-1.33.266-2.597.748-3.752A9.75 9.75 0 0 0 3 11.25A9.75 9.75 0 0 0 12.75 21a9.75 9.75 0 0 0 9.002-5.998"/></symbol><use href="#ai:heroicons:moon"></use> </svg> <svg width="1em" height="1em" data-theme-icon="auto" class="hidden w-5 h-5" data-icon="heroicons:computer-desktop"> <symbol id="ai:heroicons:computer-desktop" viewBox="0 0 24 24"><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M9 17.25v1.007a3 3 0 0 1-.879 2.122L7.5 21h9l-.621-.621A3 3 0 0 1 15 18.257V17.25m6-12V15a2.25 2.25 0 0 1-2.25 2.25H5.25A2.25 2.25 0 0 1 3 15V5.25m18 0A2.25 2.25 0 0 0 18.75 3H5.25A2.25 2.25 0 0 0 3 5.25m18 0V12a2.25 2.25 0 0 1-2.25 2.25H5.25A2.25 2.25 0 0 1 3 12V5.25"/></symbol><use href="#ai:heroicons:computer-desktop"></use> </svg> </button> <!-- Tooltip --> <div class="absolute left-1/2 -translate-x-1/2 top-full mt-2
|
|
px-2 py-1 text-xs font-medium whitespace-nowrap rounded-md shadow-sm
|
|
bg-gray-900 text-white dark:bg-white dark:text-gray-900
|
|
opacity-0 group-hover:opacity-100
|
|
transition-opacity duration-200 pointer-events-none"> <span data-tooltip-text="light" class="hidden">Light</span> <span data-tooltip-text="dark" class="hidden">Dark</span> <span data-tooltip-text="auto" class="hidden">System</span> </div> </div> <script type="module">function r(){const c=document.querySelectorAll("[data-theme-toggle]");function n(){const e=localStorage.getItem("theme");return e==="dark"||e==="light"||e==="auto"?e:"auto"}function i(){return window.matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light"}function d(e){return e==="auto"?i():e}function s(e){document.querySelectorAll("[data-theme-icon]").forEach(t=>{const a=t.dataset.themeIcon;t.classList.toggle("hidden",a!==e)}),document.querySelectorAll("[data-tooltip-text]").forEach(t=>{const a=t.dataset.tooltipText;t.classList.toggle("hidden",a!==e)})}function o(e){d(e)==="dark"?document.documentElement.classList.add("dark"):document.documentElement.classList.remove("dark"),s(e)}function u(e){localStorage.setItem("theme",e),o(e)}function l(){const e=n();return e==="light"?"dark":e==="dark"?"auto":"light"}const f=n();o(f),c.forEach(e=>{e.dataset.initialized||(e.dataset.initialized="true",e.addEventListener("click",()=>{u(l())}))}),window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change",()=>{n()==="auto"&&o("auto")})}r();document.addEventListener("astro:after-swap",r);</script> <a href="https://github.com/jimeh/common-flow" target="_blank" rel="noopener noreferrer" class="p-2 rounded-lg transition-colors
|
|
text-gray-500 dark:text-neutral-500
|
|
hover:text-gray-950 dark:hover:text-neutral-50
|
|
hover:bg-gray-100 dark:hover:bg-neutral-800" aria-label="View on GitHub"> <svg width="1em" height="1em" class="w-5 h-5" data-icon="simple-icons:github"> <symbol id="ai:simple-icons:github" viewBox="0 0 24 24"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></symbol><use href="#ai:simple-icons:github"></use> </svg> </a> </div> </div> </header> <main class="max-w-6xl mx-auto px-4 sm:px-6 py-8"> <div class="relative"> <!-- Hidden raw text for copying --> <div id="markdown-raw" class="hidden">Git Common-Flow 1.0.0-rc.2
|
|
==============================
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
Terminology
|
|
-----------
|
|
|
|
- **Master Branch** - Must always have passing tests, is considered bleeding
|
|
edge, and must be named `master`.
|
|
- **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** - 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. 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 be considered bleeding edge.
|
|
3. The master branch MUST always be in a non-broken state with its test
|
|
suite passing.
|
|
4. 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.
|
|
2. 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.
|
|
3. 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.
|
|
4. 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.
|
|
5. 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.
|
|
6. 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".
|
|
7. 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.
|
|
8. 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>
|
|
2. You SHOULD never blindly commit all changes with "git commit -a". It is
|
|
RECOMMENDED you use "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/)
|
|
</div> <!-- Highlighted code --> <div id="markdown-content" class="[&_pre]:overflow-x-auto [&_pre]:rounded-xl [&_pre]:p-6
|
|
[&_pre]:text-sm [&_pre]:leading-relaxed
|
|
[&_pre]:border [&_pre]:border-gray-200
|
|
dark:[&_pre]:border-neutral-800"><pre class="shiki shiki-themes github-light github-dark" style="background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8" tabindex="0"><code><span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">Git Common-Flow 1.0.0-rc.2</span></span>
|
|
<span class="line"><span style="color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold">==============================</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">Summary</span></span>
|
|
<span class="line"><span style="color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold">-------</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">Common-Flow is an attempt to gather a sensible selection of the most common</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">usage patterns of git into a single and concise specification. It is based on</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">the [</span><span style="color:#032F62;--shiki-light-text-decoration:underline;--shiki-dark:#DBEDFF;--shiki-dark-text-decoration:underline">original variant</span><span style="color:#24292E;--shiki-dark:#E1E4E8">](</span><span style="color:#24292E;--shiki-light-text-decoration:underline;--shiki-dark:#E1E4E8;--shiki-dark-text-decoration:underline">http://scottchacon.com/2011/08/31/github-flow.html</span><span style="color:#24292E;--shiki-dark:#E1E4E8">)</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">of [</span><span style="color:#032F62;--shiki-light-text-decoration:underline;--shiki-dark:#DBEDFF;--shiki-dark-text-decoration:underline">GitHub Flow</span><span style="color:#24292E;--shiki-dark:#E1E4E8">](</span><span style="color:#24292E;--shiki-light-text-decoration:underline;--shiki-dark:#E1E4E8;--shiki-dark-text-decoration:underline">https://guides.github.com/introduction/flow/</span><span style="color:#24292E;--shiki-dark:#E1E4E8">), while taking</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">into account how a lot of open source projects use git.</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">TL;DR: Common-Flow is basically GitHub Flow with the addition of versioned</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">releases, maintenance releases for old versions, and without the requirement to</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">deploy to production all the time.</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">Terminology</span></span>
|
|
<span class="line"><span style="color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold">-----------</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">-</span><span style="color:#24292E;--shiki-light-font-weight:bold;--shiki-dark:#E1E4E8;--shiki-dark-font-weight:bold"> **Master Branch**</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> - Must always have passing tests, is considered bleeding</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> edge, and must be named </span><span style="color:#005CC5;--shiki-dark:#79B8FF">`master`</span><span style="color:#24292E;--shiki-dark:#E1E4E8">.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">-</span><span style="color:#24292E;--shiki-light-font-weight:bold;--shiki-dark:#E1E4E8;--shiki-dark-font-weight:bold"> **Change Branches**</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> - Any branch that introduces changes like a new feature, a</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> bug fix, etc.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">-</span><span style="color:#24292E;--shiki-light-font-weight:bold;--shiki-dark:#E1E4E8;--shiki-dark-font-weight:bold"> **Source Branch**</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> - The branch that a change branch was created from. New</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> changes in the source branch should be incorporated into the change branch via</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> rebasing.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">-</span><span style="color:#24292E;--shiki-light-font-weight:bold;--shiki-dark:#E1E4E8;--shiki-dark-font-weight:bold"> **Merge Target**</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> - A branch that is the intended merge target for a change</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> branch. Typically the merge target branch will be the same as the source</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> branch.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">-</span><span style="color:#24292E;--shiki-light-font-weight:bold;--shiki-dark:#E1E4E8;--shiki-dark-font-weight:bold"> **Pull Request**</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> - A means of requesting that a change branch is merged in to</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> its merge target, allowing others to review, discuss and approve the changes.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">-</span><span style="color:#24292E;--shiki-light-font-weight:bold;--shiki-dark:#E1E4E8;--shiki-dark-font-weight:bold"> **Release**</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> - Consists of a version bump commit, and a git tag named according</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> to the new version string placed on said commit.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">-</span><span style="color:#24292E;--shiki-light-font-weight:bold;--shiki-dark:#E1E4E8;--shiki-dark-font-weight:bold"> **Release Branches**</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> - Used both for short-term preparations of a release, and</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> also for long-term maintenance of older version.</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">Git Common-Flow Specification (Common-Flow)</span></span>
|
|
<span class="line"><span style="color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold">-------------------------------------------</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">interpreted as described in [</span><span style="color:#032F62;--shiki-light-text-decoration:underline;--shiki-dark:#DBEDFF;--shiki-dark-text-decoration:underline">RFC 2119</span><span style="color:#24292E;--shiki-dark:#E1E4E8">](</span><span style="color:#24292E;--shiki-light-text-decoration:underline;--shiki-dark:#E1E4E8;--shiki-dark-text-decoration:underline">https://tools.ietf.org/html/rfc2119</span><span style="color:#24292E;--shiki-dark:#E1E4E8">).</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">1.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> The Master Branch</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 1.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> A branch named "master" MUST exist and it MUST be referred to as the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> "master branch".</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 2.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> The master branch MUST be considered bleeding edge.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 3.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> The master branch MUST always be in a non-broken state with its test</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> suite passing.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 4.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> The master branch SHOULD always be in a "as near as possibly ready for</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> release/production" state to reduce any friction with creating a new</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> release.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">2.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Change Branches</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 1.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Each change (feature, bugfix, etc.) MUST be performed on separate</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> branches that SHOULD be referred to as "change branches". All change</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> branches MUST have descriptive names. It is RECOMMENDED that you commit</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> often locally, and you SHOULD regularly push your work to the same named</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> branch on the remote server.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 2.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> You MUST create separate change branches for each distinctly different</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> change. You MUST NOT include multiple unrelated changes into a single</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> change branch.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 3.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> When a change branch is created, the branch that it is created from</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> SHOULD be referred to as the "source branch". Each change branch also</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> needs a designated "merge target" branch, typically this will be the same</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> as the source branch.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 4.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Change branches MUST be regularly updated with any changes from their</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> source branch. This MUST be done by rebasing the change branch on top of</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> the source branch.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 5.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> After rebasing a change branch on top of its source branch you MUST push</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> the change branch to the remote server. This will require you to do a</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> force push, and you SHOULD use the "--force-with-lease" git push option.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">3.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Pull Requests</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 1.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> To merge a change branch into its merge target, you MUST open a "pull</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> request" (or equivalent) so others can review and approve your changes.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 2.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> A pull request MUST only be merged when the change branch is up-to-date</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> with its source branch, the test suite is passing, and you and others are</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> happy with the change. This is especially important if the merge target</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> is the master branch.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 3.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> To get feedback, help, or generally just discuss a change branch with</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> others, the RECOMMENDED way to do so is by creating a pull request and</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> discuss the changes with others there.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">4.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Versioning</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 1.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> The project MUST have its version hard-coded somewhere in the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> code-base. It is RECOMMENDED that this is done in a file called "VERSION"</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> located in the root of the project.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 2.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> If you are using a "VERSION" file in the root of the project, this MUST</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> only contain the exact version string.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 3.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> The version string SHOULD follow the Semantic Versioning</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> (<</span><span style="color:#24292E;--shiki-light-text-decoration:underline;--shiki-dark:#E1E4E8;--shiki-dark-text-decoration:underline">http://semver.org/</span><span style="color:#24292E;--shiki-dark:#E1E4E8">>) format. Use of Semantic Versioning is OPTIONAL,</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> but the version string MUST NOT have a "v" prefix. For example "v2.11.4"</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> is bad, and "2.11.4" is good.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">5.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Releases</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 1.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> To create a new release, you MUST create a "version bump" commit which</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> changes the hard-coded version string of the project. The version bump</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> commit MUST have a git tag created on it and named as the exact version</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> string.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 2.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> If you are not using a release branch, then the version bump commit MUST</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> be created directly on the master branch.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 3.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> The version bump commit MUST have a commit message title of "Bump version</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> to VERSION". For example, if the new version string is "2.11.4", the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> first line of the commit message MUST read: "Bump version to 2.11.4"</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 4.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> The release tag on the version bump commit MUST be named exactly the same</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> as the version string. The tag name can OPTIONALLY be prefixed with</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> "v". For example the tag name can be either "2.11.4" or "v2.11.4". You</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> MUST not use a mix of "v" prefixed and non-prefixed tags. Pick one form</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> and stick to it.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 5.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> It is RECOMMENDED that release tags are lightweight tags, but you can</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> OPTIONALLY use annotated tags if you want to include changelog</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> information in the release tag itself.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 6.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> If you use annotated release tags, the first line of the annotation MUST</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> read "Release VERSION". For example for version "2.11.4" the first line</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> of the tag annotation would read "Release 2.11.4". The second line must</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> be blank, and the changelog MUST start on the third line.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">6.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Release Branches</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 1.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Any branch that has a name starting with "release-" SHOULD be referred to</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> as a "release branch".</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 2.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Use of release branches is OPTIONAL.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 3.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Changes in a release branch SHOULD typically come from work being</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> done against the master branch. Meaning changes SHOULD only trickle</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> downwards from the master branch. If a change needs to trickle back up</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> into the master branch, that work should have happened against the master</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> branch in the first place. One exception to this is version bump commits.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 4.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> There are two types of release branches; short-term, and long-term.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 5.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Short-Term Release Branches</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 1.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Used for creating a specific versioned release.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 2.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> A short-term release branch is RECOMMENDED if there is a lengthy</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> pre-release verification process to avoid a code freeze on the master</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> branch.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 3.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> MUST have a name of "release-VERSION". For example for version</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> "2.11.4" the release branch name MUST be "release-2.11.4".</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 4.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> When using a short-term release branch, the version bump commit and</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> release tag MUST be made directly on the release branch itself.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 5.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Only very minor changes should be performed on a short-term release</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> branch directly. Any larger changes SHOULD be done in the master</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> branch, and SHOULD be pulled into the release branch by rebasing it</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> on top of the master branch the same way a change branch pulls in</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> updates from its source branch.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 6.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> After the version bump commit and release tag have been created, the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> release branch MUST be merged back into its source branch and then</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> deleted. Typically the source branch will be the master branch.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 6.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Long-Term Release Branches</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 1.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Used for work on versions which are not currently part of the master</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> branch. Typically this is useful when you need to create a new</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> maintenance release for a older version.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 2.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> The branch name MUST have a non-specific version number. For example</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> a long-term release branch for creating new 2.9.x releases would be</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> named "release-2.9".</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 3.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> To create a new release from a long-term release branch, you MUST</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> create a version bump commit and release tag directly on the release</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> branch.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 4.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> A long-term release branch MUST be created from the relevant release</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> tag. For example if the master branch is on version 2.11.4 and there</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> is a security fix for all 2.9.x releases, the latest of which is</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> "2.9.7". Create a new branch called "release-2.9" off of the "2.9.7"</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> release tag. The security fix release will then end up being version</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> "2.9.8".</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">7.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Bug Fixes & Rollback</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 1.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> You MUST NOT under any circumstances force push to the master branch.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 2.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> If a change branch which has been merged into the master branch is found</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> to have a bug in it, the bug fix work MUST be done as a new separate</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> change branch and MUST follow the same workflow as any other change</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> branch.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 3.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> If a change branch is wrongfully merged into master, or for any other</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> reason the merge must be undone, you MUST undo the merge by reverting the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> merge commit itself. Effectively creating a new commit that reverses all</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> the relevant changes.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">8.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Git Best Practices</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 1.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> All commit messages SHOULD follow the Commit Guidelines and format from</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> the official git</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> documentation:</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> <</span><span style="color:#24292E;--shiki-light-text-decoration:underline;--shiki-dark:#E1E4E8;--shiki-dark-text-decoration:underline">https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project</span><span style="color:#24292E;--shiki-dark:#E1E4E8">></span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 2.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> You SHOULD never blindly commit all changes with "git commit -a". It is</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> RECOMMENDED you use "git add -i" to add individual changes to the staging</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> area so you are fully aware of what you are committing.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 3.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> You SHOULD always use "--force-with-lease" when doing a force push. The</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> regular "--force" option is dangerous and destructive. More</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> information:</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> <</span><span style="color:#24292E;--shiki-light-text-decoration:underline;--shiki-dark:#E1E4E8;--shiki-dark-text-decoration:underline">https://developer.atlassian.com/blog/2015/04/force-with-lease/</span><span style="color:#24292E;--shiki-dark:#E1E4E8">></span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 4.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> You SHOULD understand and be comfortable with</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> rebasing: <</span><span style="color:#24292E;--shiki-light-text-decoration:underline;--shiki-dark:#E1E4E8;--shiki-dark-text-decoration:underline">https://git-scm.com/book/en/v2/Git-Branching-Rebasing</span><span style="color:#24292E;--shiki-dark:#E1E4E8">></span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 5.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> It is RECOMMENDED that you always do "git pull --rebase" instead of "git</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> pull" to avoid unnecessary merge commits. You can make this the default</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> behavior of "git pull" with "git config --global pull.rebase true".</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 6.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> It is RECOMMENDED that all branches be merged using "git merge --no-ff".</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> This makes sure the reference to the original branch is kept in the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> commits, allows one to revert a merge by reverting a single merge commit,</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> and creates a merge commit to mark the integration of the branch with</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> master.</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">About</span></span>
|
|
<span class="line"><span style="color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold">-----</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">The Git Common-Flow specification is authored</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">by [</span><span style="color:#032F62;--shiki-light-text-decoration:underline;--shiki-dark:#DBEDFF;--shiki-dark-text-decoration:underline">Jim Myhrberg</span><span style="color:#24292E;--shiki-dark:#E1E4E8">](</span><span style="color:#24292E;--shiki-light-text-decoration:underline;--shiki-dark:#E1E4E8;--shiki-dark-text-decoration:underline">http://jimeh.me</span><span style="color:#24292E;--shiki-dark:#E1E4E8">).</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">If you'd like to leave feedback,</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">please [</span><span style="color:#032F62;--shiki-light-text-decoration:underline;--shiki-dark:#DBEDFF;--shiki-dark-text-decoration:underline">open an issue on GitHub</span><span style="color:#24292E;--shiki-dark:#E1E4E8">](</span><span style="color:#24292E;--shiki-light-text-decoration:underline;--shiki-dark:#E1E4E8;--shiki-dark-text-decoration:underline">https://github.com/jimeh/common-flow/issues</span><span style="color:#24292E;--shiki-dark:#E1E4E8">).</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">License</span></span>
|
|
<span class="line"><span style="color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold">-------</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">[</span><span style="color:#032F62;--shiki-light-text-decoration:underline;--shiki-dark:#DBEDFF;--shiki-dark-text-decoration:underline">Creative Commons - CC BY 3.0</span><span style="color:#24292E;--shiki-dark:#E1E4E8">](</span><span style="color:#24292E;--shiki-light-text-decoration:underline;--shiki-dark:#E1E4E8;--shiki-dark-text-decoration:underline">http://creativecommons.org/licenses/by/3.0/</span><span style="color:#24292E;--shiki-dark:#E1E4E8">)</span></span>
|
|
<span class="line"></span></code></pre></div> </div> </main> <!-- Re-init theme on Astro page transitions --> <script type="module">document.addEventListener("astro:after-swap",()=>{const e=localStorage.getItem("theme"),t=window.matchMedia("(prefers-color-scheme: dark)").matches;e==="dark"||e!=="light"&&t?document.documentElement.classList.add("dark"):document.documentElement.classList.remove("dark")});</script> </body> </html> <script type="module">function l(){const c=document.getElementById("copy-btn"),d=document.getElementById("download-btn"),n=document.getElementById("markdown-raw"),a=c?.querySelector("[data-copy-text]"),e=document.getElementById("copy-tooltip");if(!n)return;function i(){a&&(a.textContent="Copied!",setTimeout(()=>{a.textContent="Copy"},2e3)),e&&(e.classList.remove("opacity-0"),e.classList.add("opacity-100"),setTimeout(()=>{e.classList.remove("opacity-100"),e.classList.add("opacity-0")},2e3))}c&&c.addEventListener("click",async()=>{try{await navigator.clipboard.writeText(n.textContent||""),i()}catch{const t=document.createElement("textarea");t.value=n.textContent||"",t.style.position="fixed",t.style.opacity="0",document.body.appendChild(t),t.select(),document.execCommand("copy"),document.body.removeChild(t),i()}}),d&&d.addEventListener("click",()=>{const t=d.dataset.filename||"common-flow.md",m=n.textContent||"",r=new Blob([m],{type:"text/markdown"}),s=URL.createObjectURL(r),o=document.createElement("a");o.href=s,o.download=t,document.body.appendChild(o),o.click(),document.body.removeChild(o),URL.revokeObjectURL(s)})}l();document.addEventListener("astro:after-swap",l);</script> |