mirror of
https://github.com/jimeh/commonflow.org.git
synced 2026-02-19 05:46:40 +00:00
717 lines
84 KiB
HTML
717 lines
84 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.4/raw/"><title>Git Common-Flow 1.0.0-rc.4 - 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.4 - 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.4/raw/"><!-- Twitter --><meta name="twitter:card" content="summary"><meta name="twitter:title" content="Git Common-Flow 1.0.0-rc.4 - 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.4" 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.4 </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.4.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.4
|
|
===========================
|
|
|
|
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. Is
|
|
effectively just a git tag named after the version of the release.
|
|
- **Release Branches** - Used both for short-term preparations of a release, and
|
|
also for long-term maintenance of older version.
|
|
|
|
Git Common-Flow Specification (Common-Flow)
|
|
-------------------------------------------
|
|
|
|
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
|
|
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
|
|
interpreted as described in [RFC 2119](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".
|
|
2. All change branches MUST have descriptive names.
|
|
3. It is RECOMMENDED that you commit often locally, and that you try and
|
|
keep the commits reasonably structured to avoid a messy and confusing git
|
|
history.
|
|
4. You SHOULD regularly push your work to the same named branch on the
|
|
remote server.
|
|
5. You SHOULD create separate change branches for each distinctly different
|
|
change. You SHOULD NOT include multiple unrelated changes into a single
|
|
change branch.
|
|
6. 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.
|
|
7. 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.
|
|
8. After updating a change branch from its source branch you MUST push the
|
|
change branch to the remote server. Due to the nature of rebasing, you
|
|
will be required to do a force push, and you MUST use the
|
|
"--force-with-lease" git push option when doing so instead of the regular
|
|
"--force".
|
|
9. If there is a truly valid technical reason to not use rebase when
|
|
updating change branches, then you can update change branches via merge
|
|
instead of rebase. The decision to use merge MUST only be taken after all
|
|
possible options to use rebase have been tried and failed. People not
|
|
understanding how to use rebase is NOT a valid reason to use merge. If
|
|
you do decide to use merge instead of rebase, you MUST NOT use a mixture
|
|
of both methods, pick one and stick to it.
|
|
4. Pull Requests
|
|
1. To merge a change branch into its merge target, you MUST open a "pull
|
|
request" (or equivalent).
|
|
2. The purpose of a pull request is to allow others to review your changes
|
|
and give feedback. You can then fix any issues, complaints, and more that
|
|
might arise, and then let people review again.
|
|
3. Before creating a pull request, it is RECOMMENDED that you consider the
|
|
state of your change branch's commit history. If it is messy and
|
|
confusing, it might be a good idea to rebase your branch with "git rebase
|
|
-i" to present a cleaner and easier to follow commit history for your
|
|
reviewers.
|
|
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.
|
|
5. 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. A "version string" is a typically mostly numeric string that identifies a
|
|
specific version of a project. The version string itself MUST NOT have a
|
|
"v" prefix, but the version string can be displayed with a "v" prefix to
|
|
indicate it is a version that is being referred to.
|
|
2. The source of truth for a project's version MUST be a git tag with a name
|
|
based on the version string. This kind of tag MUST be referred to as a
|
|
"release tag".
|
|
3. It is OPTIONAL, but RECOMMENDED to also keep the version string
|
|
hard-coded somewhere in the project code-base.
|
|
4. If you hard-code the version string into the code-base, it is RECOMMENDED
|
|
that you do so in a file called "VERSION" located in the root of the
|
|
project. But be mindful of the conventions of your programming language
|
|
and community when choosing if, where and how to hard-code the version
|
|
string.
|
|
5. If you are using a "VERSION" file in the root of the project, this file
|
|
MUST only contain the exact version string, meaning it MUST NOT have a
|
|
"v" prefix. For example "v2.11.4" is bad, and "2.11.4" is good.
|
|
6. It is OPTIONAL, but RECOMMENDED that that the version string follows
|
|
Semantic Versioning (<http://semver.org/>).
|
|
6. Releases
|
|
1. To create a new release, you MUST create a git tag named as the exact
|
|
version string of the release. This kind of tag MUST be referred to as a
|
|
"release tag".
|
|
2. The release tag name can OPTIONALLY be prefixed with "v". For example the
|
|
tag name can be either "2.11.4" or "v2.11.4". It is however RECOMMENDED
|
|
that you do not use a "v" prefix. You MUST NOT use a mixture of "v"
|
|
prefixed and non-prefixed tags. Pick one form and stick to it.
|
|
3. If the version string is hard-coded into the code-base, you MUST create a
|
|
"version bump" commit which changes the hard-coded version string of the
|
|
project.
|
|
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
|
|
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",
|
|
the first line of the commit message SHOULD read: "Bump version to
|
|
2.11.4"
|
|
7. 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.
|
|
8. If you use annotated release tags, the first line of the annotation
|
|
SHOULD read "Release VERSION". For example for version "2.11.4" the first
|
|
line of the tag annotation SHOULD read "Release 2.11.4". The second line
|
|
MUST be blank, and the changelog MUST start on the third line.
|
|
7. Short-Term Release Branches
|
|
1. Any branch that has a name starting with "release-" SHOULD be referred to
|
|
as a "release branch".
|
|
2. Any release branch which has a name ending with a specific version
|
|
string, MUST be referred to as a "short-term release branch".
|
|
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
|
|
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
|
|
"release-2.11.4".
|
|
6. When using a short-term release branch to create a release, the release
|
|
tag and if used, version bump commit, MUST be placed directly on the
|
|
short-term release branch itself.
|
|
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,
|
|
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.
|
|
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.
|
|
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
|
|
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
|
|
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".
|
|
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
|
|
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
|
|
to long-term release branches.
|
|
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.
|
|
10. 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 -i" or "git add -p" 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.
|
|
|
|
FAQ
|
|
---
|
|
|
|
### Why use Common-Flow instead of Git Flow, and how does it differ?
|
|
|
|
Common-Flow tries to be a lot less complicated than Git Flow by having fewer
|
|
types of branches, and simpler rules. Normal day to day development doesn't
|
|
really change much:
|
|
|
|
- You create change branches instead of feature branches, without the need of a
|
|
"feature/" or "change/" prefix in the branch name.
|
|
- Change branches are typically created off of and merged back into "master"
|
|
instead of "develop".
|
|
- Creating a release is done by simply creating a git tag, typically on the
|
|
master branch.
|
|
|
|
In detail, the main differences between Git Flow and Common-Flow are:
|
|
|
|
- There is no "develop" branch, there is only a "master" branch which contains
|
|
the latest work. In Git Flow the master branch effectively ends up just being
|
|
a pointer to the latest release, despite the fact that Git Flow includes
|
|
release tags too. In Common-Flow you just look at the tags to find the latest
|
|
release.
|
|
- There are no "feature" or "hotfix" branches, there's only "change"
|
|
branches. Any branch that is not master and introduces changes is a change
|
|
branch. Change branches also don't have a enforced naming convention, they
|
|
just have to have a "descriptive name". This makes things simpler and allows
|
|
more flexibility.
|
|
- Release branches are available, but optional. Instead of enforcing the use of
|
|
release branches like Git Flow, Common-Flow only recommends the use of release
|
|
branches when it makes things easier. If creating a new release by tagging
|
|
"master" works for you, great, do that.
|
|
|
|
### Why use Common-Flow instead of GitHub Flow, and how does it differ?
|
|
|
|
Common-Flow is essentially GitHub Flow with the addition of a "Release" concept
|
|
that uses tags. It also attempts to define how certain common tasks are done,
|
|
like updating change/feature branches from their source branches for
|
|
example. This is to help end arguments about how such things are done.
|
|
|
|
If a deployment/release for you is just getting the latest code in the master
|
|
branch out, without caring about bumping version numbers or anything, then
|
|
GitHub Flow is a good fit for you, and you probably don't need the extras of
|
|
Common-Flow.
|
|
|
|
However if your deployments/releases have specific version numbers, then
|
|
Common-Flow gives you a simple set of rules of how to create and manage
|
|
releases, on top of what GitHub Flow already does.
|
|
|
|
### What does "descriptive name" mean for change branches?
|
|
|
|
It means what it sounds like. The name should be descriptive, as in by just
|
|
reading the name of the branch you should understand what the branch's purpose
|
|
is and what it does. Here's a few examples:
|
|
|
|
- add-2fa-support
|
|
- fix-login-issue
|
|
- remove-sort-by-middle-name-functionality
|
|
- update-font-awesome
|
|
- change-search-behavior
|
|
- tweak-footer-style
|
|
|
|
Notice how none of these have any prefixes like "feature/" or "hotfix/", they're
|
|
not needed when branch names are properly descriptive. However there's nothing
|
|
to say you can't use such prefixes if you want. That also means that you can add
|
|
ticket number prefixes if your team/org has that as part of it's process.
|
|
|
|
### How do we release an emergency hotfix when the master branch is broken?
|
|
|
|
This should ideally never happen, however if it does you can do one of the
|
|
following:
|
|
|
|
- Review why the master branch is broken and revert the changes that caused the
|
|
issues. Then apply the hotfix and release.
|
|
- Or use a short-term release branch created from the latest release tag instead
|
|
of the master branch. Apply the hotfix to the release branch, create a release
|
|
tag on the release branch, and then merge it back into master.
|
|
|
|
In this situation, it is recommended you try to revert the offending changes
|
|
that's preventing a new release from master. But if that proves to be a
|
|
complicated task and you're short on time, a short-term release branch gives you
|
|
a instant fix to the situation at hand, and let's you resolve the issues with
|
|
the master branch when you have more time on your hands.
|
|
|
|
About
|
|
-----
|
|
|
|
The Git Common-Flow specification is authored
|
|
by [Jim Myhrberg](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.4</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">In short, Common-Flow is essentially GitHub Flow with the addition of versioned</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">releases, optional release branches, and without the requirement to deploy to</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">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 be named "master", must always have passing tests,</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> and is not guaranteed to always work in production environments.</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"> - May be considered safe to use in production environments. Is</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> effectively just a git tag named after the version of the release.</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"> TL;DR</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 1.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Don't break the master branch.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 2.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> A release is a git tag.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">2.</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 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 IS NOT guaranteed to always work in production</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> environments. Despite test suites passing it may at times contain</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> unfinished work. Only releases may be considered safe for production use.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 5.</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">3.</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".</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 2.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> All change branches MUST have descriptive names.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 3.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> It is RECOMMENDED that you commit often locally, and that you try and</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> keep the commits reasonably structured to avoid a messy and confusing git</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> history.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 4.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> You SHOULD regularly push your work to the same named branch on the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> remote server.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 5.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> You SHOULD create separate change branches for each distinctly different</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> change. You SHOULD 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"> 6.</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"> 7.</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"> 8.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> After updating a change branch from its source branch you MUST push the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> change branch to the remote server. Due to the nature of rebasing, you</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> will be required to do a force push, and you MUST use the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> "--force-with-lease" git push option when doing so instead of the regular</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> "--force".</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 9.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> If there is a truly valid technical reason to not use rebase when</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> updating change branches, then you can update change branches via merge</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> instead of rebase. The decision to use merge MUST only be taken after all</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> possible options to use rebase have been tried and failed. People not</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> understanding how to use rebase is NOT a valid reason to use merge. If</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> you do decide to use merge instead of rebase, you MUST NOT use a mixture</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> of both methods, pick one and stick to it.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">4.</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).</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 2.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> The purpose of a pull request is to allow others to review your changes</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> and give feedback. You can then fix any issues, complaints, and more that</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> might arise, and then let people review again.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 3.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Before creating a pull request, it is RECOMMENDED that you consider the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> state of your change branch's commit history. If it is messy and</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> confusing, it might be a good idea to rebase your branch with "git rebase</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> -i" to present a cleaner and easier to follow commit history for your</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> reviewers.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 4.</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"> 5.</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">5.</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"> A "version string" is a typically mostly numeric string that identifies a</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> specific version of a project. The version string itself MUST NOT have a</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> "v" prefix, but the version string can be displayed with a "v" prefix to</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> indicate it is a version that is being referred to.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 2.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> The source of truth for a project's version MUST be a git tag with a name</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> based on the version string. This kind of tag MUST be referred to as a</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> "release tag".</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 3.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> It is OPTIONAL, but RECOMMENDED to also keep the version string</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> hard-coded somewhere in the project code-base.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 4.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> If you hard-code the version string into the code-base, it is RECOMMENDED</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> that you do so in a file called "VERSION" located in the root of the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> project. But be mindful of the conventions of your programming language</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> and community when choosing if, where and how to hard-code the 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"> 5.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> If you are using a "VERSION" file in the root of the project, this file</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> MUST only contain the exact version string, meaning it MUST NOT have a</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> "v" prefix. For example "v2.11.4" is bad, and "2.11.4" is good.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 6.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> It is OPTIONAL, but RECOMMENDED that that the version string follows</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> Semantic Versioning (<</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">>).</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">6.</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 git tag named as the exact</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> version string of the release. This kind of tag MUST be referred to as a</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> "release tag".</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 2.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> The release tag name can OPTIONALLY be prefixed with "v". For example the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> tag name can be either "2.11.4" or "v2.11.4". It is however RECOMMENDED</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> that you do not use a "v" prefix. You MUST NOT use a mixture of "v"</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> prefixed and non-prefixed tags. Pick one form and stick to it.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 3.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> If the version string is hard-coded into the code-base, you MUST create a</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> "version bump" commit which changes the hard-coded version string of the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> project.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 4.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> When using version bump commits, the release tag MUST be placed on the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> version bump commit.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 5.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> If you are not using a release branch, then the release tag, and if</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> relevant the version bump commit, MUST be created directly 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"> 6.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> The version bump commit SHOULD have a commit message title of "Bump</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> version to VERSION". For example, if the new version string is "2.11.4",</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> the first line of the commit message SHOULD read: "Bump version to</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> 2.11.4"</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 7.</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"> 8.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> If you use annotated release tags, the first line of the annotation</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> SHOULD read "Release VERSION". For example for version "2.11.4" the first</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> line of the tag annotation SHOULD read "Release 2.11.4". The second line</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> MUST be blank, and the changelog MUST start on the third line.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">7.</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"> 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"> Any release branch which has a name ending with a specific version</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> string, MUST be referred to as a "short-term release branch".</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 3.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Use of short-term release branches are OPTIONAL, and intended to be used</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> to create a specific versioned release.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 4.</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"> 5.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Short-term release branches MUST have a name of "release-VERSION". For</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> example for version "2.11.4" the release branch name MUST be</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> "release-2.11.4".</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 6.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> When using a short-term release branch to create a release, the release</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> tag and if used, version bump commit, MUST be placed directly on the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> short-term release branch itself.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 7.</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 branch,</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> and SHOULD be pulled into the release branch by rebasing it on top of the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> master branch the same way a change branch pulls in updates from its</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> source branch.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 8.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> After a release tag has been created, the release branch MUST be merged</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> back into its source branch and then deleted. Typically the source branch</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> will be the master branch.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">8.</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"> Any release branch which has a name ending with a non-specific version</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> string, MUST be referred to as a "long-term release branch". For example</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> "release-2.11" is a long-term release branch, while "release-2.11.4" is a</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> short-term 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 long-term release branches are OPTIONAL, and intended for work on</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> versions which are not currently part of the master branch. Typically</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> this is useful when you need to create a new maintenance release for a</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> older version.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 3.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> A long-term release branch MUST have a name with a non-specific version</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> number. For example a long-term release branch for creating new 2.9.x</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> releases MUST be named "release-2.9".</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 4.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Long-term release branches for maintenance releases of older versions</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> MUST be created from the relevant release tag. For example if the master</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> branch is on version 2.11.4 and there is a security fix for all 2.9.x</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> releases, the latest of which is "2.9.7". Create a new branch called</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> "release-2.9" off of the "2.9.7" release tag. The security fix release</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> will then end up being version "2.9.8".</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 5.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> To create a new release from a long-term release branch, you MUST follow</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> the same process as a release from the master branch, except the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> long-term release branch takes the place of the master branch.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70"> 7.</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> A long-term release branch should be treated with the same respect as the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> master branch. It is effectively the master branch for the release series</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> in question. Meaning it MUST always be in a non-broken state, MUST NOT be</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> force pushed to, etc.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">9.</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 or</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> to long-term release branches.</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">10.</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#_commit_guidelines</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" or "git add -p" to add individual</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> changes to the staging area so you are fully aware of what you are</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> 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">FAQ</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:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold">### Why use Common-Flow instead of Git Flow, and how does it differ?</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">Common-Flow tries to be a lot less complicated than Git Flow by having fewer</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">types of branches, and simpler rules. Normal day to day development doesn't</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">really change much:</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">-</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> You create change branches instead of feature branches, without the need of a</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> "feature/" or "change/" prefix in the branch name.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">-</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Change branches are typically created off of and merged back into "master"</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> instead of "develop".</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">-</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Creating a release is done by simply creating a git tag, typically on the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> master branch.</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">In detail, the main differences between Git Flow and Common-Flow are:</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">-</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> There is no "develop" branch, there is only a "master" branch which contains</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> the latest work. In Git Flow the master branch effectively ends up just being</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> a pointer to the latest release, despite the fact that Git Flow includes</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> release tags too. In Common-Flow you just look at the tags to find the latest</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">-</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> There are no "feature" or "hotfix" branches, there's only "change"</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> branches. Any branch that is not master and introduces changes is a change</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> branch. Change branches also don't have a enforced naming convention, they</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> just have to have a "descriptive name". This makes things simpler and allows</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> more flexibility.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">-</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Release branches are available, but optional. Instead of enforcing the use of</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> release branches like Git Flow, Common-Flow only recommends the use of release</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> branches when it makes things easier. If creating a new release by tagging</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> "master" works for you, great, do that.</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold">### Why use Common-Flow instead of GitHub Flow, and how does it differ?</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">Common-Flow is essentially GitHub Flow with the addition of a "Release" concept</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">that uses tags. It also attempts to define how certain common tasks are done,</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">like updating change/feature branches from their source branches for</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">example. This is to help end arguments about how such things are done.</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">If a deployment/release for you is just getting the latest code in the master</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">branch out, without caring about bumping version numbers or anything, then</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">GitHub Flow is a good fit for you, and you probably don't need the extras of</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">Common-Flow.</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">However if your deployments/releases have specific version numbers, then</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">Common-Flow gives you a simple set of rules of how to create and manage</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">releases, on top of what GitHub Flow already does.</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold">### What does "descriptive name" mean for change branches?</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">It means what it sounds like. The name should be descriptive, as in by just</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">reading the name of the branch you should understand what the branch's purpose</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">is and what it does. Here's a few examples:</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">-</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> add-2fa-support</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">-</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> fix-login-issue</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">-</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> remove-sort-by-middle-name-functionality</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">-</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> update-font-awesome</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">-</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> change-search-behavior</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">-</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> tweak-footer-style</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">Notice how none of these have any prefixes like "feature/" or "hotfix/", they're</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">not needed when branch names are properly descriptive. However there's nothing</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">to say you can't use such prefixes if you want. That also means that you can add</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">ticket number prefixes if your team/org has that as part of it's process.</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold">### How do we release an emergency hotfix when the master branch is broken?</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">This should ideally never happen, however if it does you can do one of the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">following:</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">-</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Review why the master branch is broken and revert the changes that caused the</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> issues. Then apply the hotfix and release.</span></span>
|
|
<span class="line"><span style="color:#E36209;--shiki-dark:#FFAB70">-</span><span style="color:#24292E;--shiki-dark:#E1E4E8"> Or use a short-term release branch created from the latest release tag instead</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> of the master branch. Apply the hotfix to the release branch, create a release</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8"> tag on the release branch, and then merge it back into master.</span></span>
|
|
<span class="line"></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">In this situation, it is recommended you try to revert the offending changes</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">that's preventing a new release from master. But if that proves to be a</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">complicated task and you're short on time, a short-term release branch gives you</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">a instant fix to the situation at hand, and let's you resolve the issues with</span></span>
|
|
<span class="line"><span style="color:#24292E;--shiki-dark:#E1E4E8">the master branch when you have more time on your hands.</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> |