{
- items.map((item, index) => (
+ items.map((item) => (
= navbarHeight) {
header.classList.remove("translate-y-[-100%]", "border-transparent");
header.classList.add("border-gray-200", "dark:border-neutral-800");
@@ -191,7 +192,9 @@ const { version } = Astro.props;
}
}
- window.addEventListener("scroll", updateHeaderVisibility, { passive: true });
+ window.addEventListener("scroll", updateHeaderVisibility, {
+ passive: true,
+ });
updateHeaderVisibility();
// Mobile menu toggle
diff --git a/src/components/Hero.astro b/src/components/Hero.astro
index c655a8b..09305f6 100644
--- a/src/components/Hero.astro
+++ b/src/components/Hero.astro
@@ -37,7 +37,7 @@ const { version, svgPath } = Astro.props;
diff --git a/src/components/SpecSidebar.astro b/src/components/SpecSidebar.astro
index e3720a2..dd53d87 100644
--- a/src/components/SpecSidebar.astro
+++ b/src/components/SpecSidebar.astro
@@ -207,7 +207,7 @@ const { items } = Astro.props;
([entry]) => {
toggleBtn.classList.toggle("hidden", !entry.isIntersecting);
},
- { threshold: 0 }
+ { threshold: 0 },
);
specObserver.observe(specSection);
}
diff --git a/src/components/ThemeToggle.astro b/src/components/ThemeToggle.astro
index 11583cd..7afc284 100644
--- a/src/components/ThemeToggle.astro
+++ b/src/components/ThemeToggle.astro
@@ -12,52 +12,55 @@
hover:bg-gray-100 dark:hover:bg-neutral-800"
aria-label="Toggle theme"
>
-
-
-
-
-
-
+ 12a4 4 0 11-8 0 4 4 0 018 0z"
+ >
+
+
+
+
+
;
function getStoredMode(): ThemeMode {
diff --git a/src/components/VersionSelector.astro b/src/components/VersionSelector.astro
index a2b9c1b..065f247 100644
--- a/src/components/VersionSelector.astro
+++ b/src/components/VersionSelector.astro
@@ -81,10 +81,10 @@ const { currentVersion, versions } = Astro.props;
(selector as HTMLElement).dataset.initialized = "true";
const trigger = selector.querySelector(
- "[data-version-trigger]"
+ "[data-version-trigger]",
) as HTMLButtonElement;
const dropdown = selector.querySelector(
- "[data-version-dropdown]"
+ "[data-version-dropdown]",
) as HTMLElement;
const arrow = selector.querySelector("[data-arrow-icon]") as HTMLElement;
@@ -117,7 +117,11 @@ const { currentVersion, versions } = Astro.props;
if (a) a.style.transform = "";
});
- isOpen ? close() : open();
+ if (isOpen) {
+ close();
+ } else {
+ open();
+ }
});
document.addEventListener("click", (e) => {
diff --git a/src/content/spec/1.0.0-rc.1.md b/src/content/spec/1.0.0-rc.1.md
index a234fe4..1459511 100644
--- a/src/content/spec/1.0.0-rc.1.md
+++ b/src/content/spec/1.0.0-rc.1.md
@@ -2,13 +2,12 @@
title: Git Common-Flow 1.0.0-rc.1
version: 1.0.0-rc.1
---
-Git Common-Flow 1.0.0-rc.1
-==============================
+
+# Git Common-Flow 1.0.0-rc.1
-Summary
--------
+## 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
@@ -20,8 +19,7 @@ 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
------------
+## Terminology
- **Master Branch** - Must always have passing tests, is considered bleeding
edge, and must be named `master`.
@@ -45,131 +43,129 @@ Terminology
commit and release tag are on a maintenance branch instead of the master
branch.
-Git Common-Flow Specification (Common-Flow)
--------------------------------------------
+## 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 possible ready for
- release/production" state to reduce the friction of creating a new
- release.
+ 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 possible ready for
+ release/production" state to reduce the friction of creating a new
+ release.
2. Changes
- 1. Changes MUST be performed on a separate branch that SHOULD be referred to
- as a "change branch". All change branches MUST have descriptive names. It
- is RECOMMENDED that you commit often locally, and you SHOULD regularly
- push your work to the same named branch on the remote server.
- 2. 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.
- 3. Change branches MUST be regularly updated with any changes from their
- source branch. This MUST be done by rebasing the change branch on top of
- the source branch. To be clear you MUST NOT merge a source branch into a
- change branch.
- 4. After rebasing a change branch on top of its source branch you MUST push
- the change branch to the remote server. This will require you do a force
- push, and you SHOULD use the "--force-with-lease" git push option.
- 5. To merge a change branch into its merge target branch, you MUST open a
- "pull request" (or equivalent) so others can review and approve your
- changes.
- 6. 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.
- 7. To get feedback, help, or generally just discuss a change branch with
- others, it is RECOMMENDED you do this by creating a pull request and
- discuss the changes with others there.
+ 1. Changes MUST be performed on a separate branch that SHOULD be referred to
+ as a "change branch". All change branches MUST have descriptive names. It
+ is RECOMMENDED that you commit often locally, and you SHOULD regularly
+ push your work to the same named branch on the remote server.
+ 2. 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.
+ 3. Change branches MUST be regularly updated with any changes from their
+ source branch. This MUST be done by rebasing the change branch on top of
+ the source branch. To be clear you MUST NOT merge a source branch into a
+ change branch.
+ 4. After rebasing a change branch on top of its source branch you MUST push
+ the change branch to the remote server. This will require you do a force
+ push, and you SHOULD use the "--force-with-lease" git push option.
+ 5. To merge a change branch into its merge target branch, you MUST open a
+ "pull request" (or equivalent) so others can review and approve your
+ changes.
+ 6. 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.
+ 7. To get feedback, help, or generally just discuss a change branch with
+ others, it is RECOMMENDED you do this by creating a pull request and
+ discuss the changes with others there.
3. Git Best Practices
- 1. All commit messages SHOULD follow the Commit Guidelines and format from
- the official git
- documentation:
-
- 2. You SHOULD always use "--force-with-lease" when doing a force push. The
- plain "--force" option is dangerous and destructive. More
- information:
-
- 4. 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".
- 5. 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.
+ 1. All commit messages SHOULD follow the Commit Guidelines and format from
+ the official git
+ documentation:
+
+ 2. You SHOULD always use "--force-with-lease" when doing a force push. The
+ plain "--force" option is dangerous and destructive. More
+ information:
+
+ 4. 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".
+ 5. 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.
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
- (
-Summary
--------
+## 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
@@ -20,8 +19,7 @@ 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
------------
+## Terminology
- **Master Branch** - Must always have passing tests, is considered bleeding
edge, and must be named `master`.
@@ -40,161 +38,159 @@ Terminology
- **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)
--------------------------------------------
+## 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.
+ 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.
+ 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.
+ 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
- (
- 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:
-
- 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.
+ 1. All commit messages SHOULD follow the Commit Guidelines and format from
+ the official git
+ documentation:
+
+ 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:
+
+ 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
------
+## About
The Git Common-Flow specification is authored
by [Jim Myhrberg](http://jimeh.me).
@@ -202,7 +198,6 @@ 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
--------
+## License
[Creative Commons - CC BY 3.0](http://creativecommons.org/licenses/by/3.0/)
diff --git a/src/content/spec/1.0.0-rc.3.md b/src/content/spec/1.0.0-rc.3.md
index e6aeab7..90c64f4 100644
--- a/src/content/spec/1.0.0-rc.3.md
+++ b/src/content/spec/1.0.0-rc.3.md
@@ -2,13 +2,12 @@
title: Git Common-Flow 1.0.0-rc.3
version: 1.0.0-rc.3
---
-Git Common-Flow 1.0.0-rc.3
-===========================
+
+# Git Common-Flow 1.0.0-rc.3
-Summary
--------
+## 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
@@ -20,8 +19,7 @@ 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
------------
+## Terminology
- **Master Branch** - Must be named "master", must always have passing tests,
and is not guaranteed to always work in production environments.
@@ -41,166 +39,164 @@ Terminology
- **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)
--------------------------------------------
+## 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.
+ 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.
+ 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.
+ 3. 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.
+ 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.
3. Change Branches
- 1. Each change (feature, bugfix, etc.) MUST be performed on separate
- branches that SHOULD be referred to as "change branches". All change
- branches MUST have descriptive names. It is RECOMMENDED that you commit
- often locally, and you SHOULD regularly push your work to the same named
- branch on the remote server.
- 2. You MUST create separate change branches for each distinctly different
- change. You MUST NOT include multiple unrelated changes into a single
- change branch.
- 3. When a change branch is created, the branch that it is created from
- SHOULD be referred to as the "source branch". Each change branch also
- needs a designated "merge target" branch, typically this will be the same
- as the source branch.
- 4. Change branches MUST be regularly updated with any changes from their
- source branch. This MUST be done by rebasing the change branch on top of
- the source branch.
- 5. After rebasing a change branch on top of its source branch you MUST push
- the change branch to the remote server. This will require you to do a
- force push, and you SHOULD use the "--force-with-lease" git push option.
+ 1. Each change (feature, bugfix, etc.) MUST be performed on separate
+ branches that SHOULD be referred to as "change branches". All change
+ branches MUST have descriptive names. It is RECOMMENDED that you commit
+ often locally, and you SHOULD regularly push your work to the same named
+ branch on the remote server.
+ 2. You MUST create separate change branches for each distinctly different
+ change. You MUST NOT include multiple unrelated changes into a single
+ change branch.
+ 3. When a change branch is created, the branch that it is created from
+ SHOULD be referred to as the "source branch". Each change branch also
+ needs a designated "merge target" branch, typically this will be the same
+ as the source branch.
+ 4. Change branches MUST be regularly updated with any changes from their
+ source branch. This MUST be done by rebasing the change branch on top of
+ the source branch.
+ 5. After rebasing a change branch on top of its source branch you MUST push
+ the change branch to the remote server. This will require you to do a
+ force push, and you SHOULD use the "--force-with-lease" git push option.
4. Pull Requests
- 1. To merge a change branch into its merge target, you MUST open a "pull
- request" (or equivalent) so others can review and approve your changes.
- 2. A pull request MUST only be merged when the change branch is up-to-date
- with its source branch, the test suite is passing, and you and others are
- happy with the change. This is especially important if the merge target
- is the master branch.
- 3. To get feedback, help, or generally just discuss a change branch with
- others, the RECOMMENDED way to do so is by creating a pull request and
- discuss the changes with others there.
+ 1. To merge a change branch into its merge target, you MUST open a "pull
+ request" (or equivalent) so others can review and approve your changes.
+ 2. A pull request MUST only be merged when the change branch is up-to-date
+ with its source branch, the test suite is passing, and you and others are
+ happy with the change. This is especially important if the merge target
+ is the master branch.
+ 3. To get feedback, help, or generally just discuss a change branch with
+ others, the RECOMMENDED way to do so is by creating a pull request and
+ discuss the changes with others there.
5. Versioning
- 1. The project MUST have its version hard-coded somewhere in the
- code-base. It is RECOMMENDED that this is done in a file called "VERSION"
- located in the root of the project.
- 2. If you are using a "VERSION" file in the root of the project, this MUST
- only contain the exact version string.
- 3. The version string SHOULD follow the Semantic Versioning
- (
- 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:
-
- 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.
+ 1. All commit messages SHOULD follow the Commit Guidelines and format from
+ the official git
+ documentation:
+
+ 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:
+
+ 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
------
+## About
The Git Common-Flow specification is authored
by [Jim Myhrberg](http://jimeh.me).
@@ -208,7 +204,6 @@ 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
--------
+## License
[Creative Commons - CC BY 3.0](http://creativecommons.org/licenses/by/3.0/)
diff --git a/src/content/spec/1.0.0-rc.4.md b/src/content/spec/1.0.0-rc.4.md
index b7fb974..66b92c1 100644
--- a/src/content/spec/1.0.0-rc.4.md
+++ b/src/content/spec/1.0.0-rc.4.md
@@ -2,13 +2,12 @@
title: Git Common-Flow 1.0.0-rc.4
version: 1.0.0-rc.4
---
-Git Common-Flow 1.0.0-rc.4
-===========================
+
+# Git Common-Flow 1.0.0-rc.4
-Summary
--------
+## 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
@@ -20,8 +19,7 @@ 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
------------
+## Terminology
- **Master Branch** - Must be named "master", must always have passing tests,
and is not guaranteed to always work in production environments.
@@ -40,183 +38,182 @@ Terminology
- **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)
--------------------------------------------
+## 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.
+ 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.
+ 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.
+ 3. 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.
+ 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.
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.
+ 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.
+ 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 (
-Introduction
-------------
+## Introduction
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
@@ -20,8 +19,7 @@ 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.
-Summary
--------
+## Summary
- The "master" branch is the mainline branch with latest changes, and must not
be broken.
@@ -34,8 +32,7 @@ Summary
- Release branches can be used to avoid change freezes on master. They are not
required, instead they are available if you need them.
-Terminology
------------
+## Terminology
- **Master Branch** - Must be named "master", must always have passing tests,
and is not guaranteed to always work in production environments.
@@ -54,184 +51,183 @@ Terminology
- **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)
--------------------------------------------
+## 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. Do not break the master branch.
- 2. A release is a git tag.
+ 1. Do not 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.
- 3. 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.
- 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.
+ 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.
+ 3. 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.
+ 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.
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.
+ 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, it is RECOMMENDED you create a pull request and discuss the
- changes with others there. This leaves a clear and visible history of
- how, when, and why the code looks and behaves the way it does.
+ 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, it is RECOMMENDED you create a pull request and discuss the
+ changes with others there. This leaves a clear and visible history of
+ how, when, and why the code looks and behaves the way it does.
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 (
-Summary
--------
+## 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
@@ -20,8 +19,7 @@ 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
------------
+## Terminology
- **Master Branch** - Must always have passing tests, is considered bleeding
edge, and must be named `master`.
@@ -45,131 +43,129 @@ Terminology
commit and release tag are on a maintenance branch instead of the master
branch.
-Git Common-Flow Specification (Common-Flow)
--------------------------------------------
+## 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 possible ready for
- release/production" state to reduce the friction of creating a new
- release.
+ 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 possible ready for
+ release/production" state to reduce the friction of creating a new
+ release.
2. Changes
- 1. Changes MUST be performed on a separate branch that SHOULD be referred to
- as a "change branch". All change branches MUST have descriptive names. It
- is RECOMMENDED that you commit often locally, and you SHOULD regularly
- push your work to the same named branch on the remote server.
- 2. 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.
- 3. Change branches MUST be regularly updated with any changes from their
- source branch. This MUST be done by rebasing the change branch on top of
- the source branch. To be clear you MUST NOT merge a source branch into a
- change branch.
- 4. After rebasing a change branch on top of its source branch you MUST push
- the change branch to the remote server. This will require you do a force
- push, and you SHOULD use the "--force-with-lease" git push option.
- 5. To merge a change branch into its merge target branch, you MUST open a
- "pull request" (or equivalent) so others can review and approve your
- changes.
- 6. 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.
- 7. To get feedback, help, or generally just discuss a change branch with
- others, it is RECOMMENDED you do this by creating a pull request and
- discuss the changes with others there.
+ 1. Changes MUST be performed on a separate branch that SHOULD be referred to
+ as a "change branch". All change branches MUST have descriptive names. It
+ is RECOMMENDED that you commit often locally, and you SHOULD regularly
+ push your work to the same named branch on the remote server.
+ 2. 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.
+ 3. Change branches MUST be regularly updated with any changes from their
+ source branch. This MUST be done by rebasing the change branch on top of
+ the source branch. To be clear you MUST NOT merge a source branch into a
+ change branch.
+ 4. After rebasing a change branch on top of its source branch you MUST push
+ the change branch to the remote server. This will require you do a force
+ push, and you SHOULD use the "--force-with-lease" git push option.
+ 5. To merge a change branch into its merge target branch, you MUST open a
+ "pull request" (or equivalent) so others can review and approve your
+ changes.
+ 6. 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.
+ 7. To get feedback, help, or generally just discuss a change branch with
+ others, it is RECOMMENDED you do this by creating a pull request and
+ discuss the changes with others there.
3. Git Best Practices
- 1. All commit messages SHOULD follow the Commit Guidelines and format from
- the official git
- documentation:
-
-Summary
--------
+## 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
@@ -20,8 +19,7 @@ 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
------------
+## Terminology
- **Master Branch** - Must always have passing tests, is considered bleeding
edge, and must be named `master`.
@@ -40,161 +38,159 @@ Terminology
- **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)
--------------------------------------------
+## 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.
+ 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.
+ 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.
+ 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
- (
-Summary
--------
+## 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
@@ -20,8 +19,7 @@ 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
------------
+## Terminology
- **Master Branch** - Must be named "master", must always have passing tests,
and is not guaranteed to always work in production environments.
@@ -41,166 +39,164 @@ Terminology
- **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)
--------------------------------------------
+## 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.
+ 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.
+ 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.
+ 3. 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.
+ 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.
3. Change Branches
- 1. Each change (feature, bugfix, etc.) MUST be performed on separate
- branches that SHOULD be referred to as "change branches". All change
- branches MUST have descriptive names. It is RECOMMENDED that you commit
- often locally, and you SHOULD regularly push your work to the same named
- branch on the remote server.
- 2. You MUST create separate change branches for each distinctly different
- change. You MUST NOT include multiple unrelated changes into a single
- change branch.
- 3. When a change branch is created, the branch that it is created from
- SHOULD be referred to as the "source branch". Each change branch also
- needs a designated "merge target" branch, typically this will be the same
- as the source branch.
- 4. Change branches MUST be regularly updated with any changes from their
- source branch. This MUST be done by rebasing the change branch on top of
- the source branch.
- 5. After rebasing a change branch on top of its source branch you MUST push
- the change branch to the remote server. This will require you to do a
- force push, and you SHOULD use the "--force-with-lease" git push option.
+ 1. Each change (feature, bugfix, etc.) MUST be performed on separate
+ branches that SHOULD be referred to as "change branches". All change
+ branches MUST have descriptive names. It is RECOMMENDED that you commit
+ often locally, and you SHOULD regularly push your work to the same named
+ branch on the remote server.
+ 2. You MUST create separate change branches for each distinctly different
+ change. You MUST NOT include multiple unrelated changes into a single
+ change branch.
+ 3. When a change branch is created, the branch that it is created from
+ SHOULD be referred to as the "source branch". Each change branch also
+ needs a designated "merge target" branch, typically this will be the same
+ as the source branch.
+ 4. Change branches MUST be regularly updated with any changes from their
+ source branch. This MUST be done by rebasing the change branch on top of
+ the source branch.
+ 5. After rebasing a change branch on top of its source branch you MUST push
+ the change branch to the remote server. This will require you to do a
+ force push, and you SHOULD use the "--force-with-lease" git push option.
4. Pull Requests
- 1. To merge a change branch into its merge target, you MUST open a "pull
- request" (or equivalent) so others can review and approve your changes.
- 2. A pull request MUST only be merged when the change branch is up-to-date
- with its source branch, the test suite is passing, and you and others are
- happy with the change. This is especially important if the merge target
- is the master branch.
- 3. To get feedback, help, or generally just discuss a change branch with
- others, the RECOMMENDED way to do so is by creating a pull request and
- discuss the changes with others there.
+ 1. To merge a change branch into its merge target, you MUST open a "pull
+ request" (or equivalent) so others can review and approve your changes.
+ 2. A pull request MUST only be merged when the change branch is up-to-date
+ with its source branch, the test suite is passing, and you and others are
+ happy with the change. This is especially important if the merge target
+ is the master branch.
+ 3. To get feedback, help, or generally just discuss a change branch with
+ others, the RECOMMENDED way to do so is by creating a pull request and
+ discuss the changes with others there.
5. Versioning
- 1. The project MUST have its version hard-coded somewhere in the
- code-base. It is RECOMMENDED that this is done in a file called "VERSION"
- located in the root of the project.
- 2. If you are using a "VERSION" file in the root of the project, this MUST
- only contain the exact version string.
- 3. The version string SHOULD follow the Semantic Versioning
- (
-Summary
--------
+## 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
@@ -20,8 +19,7 @@ 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
------------
+## Terminology
- **Master Branch** - Must be named "master", must always have passing tests,
and is not guaranteed to always work in production environments.
@@ -40,183 +38,182 @@ Terminology
- **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)
--------------------------------------------
+## 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.
+ 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.
+ 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.
+ 3. 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.
+ 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.
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.
+ 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.
+ 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 (
-Introduction
-------------
+## Introduction
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
@@ -20,8 +19,7 @@ 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.
-Summary
--------
+## Summary
- The "master" branch is the mainline branch with latest changes, and must not
be broken.
@@ -34,8 +32,7 @@ Summary
- Release branches can be used to avoid change freezes on master. They are not
required, instead they are available if you need them.
-Terminology
------------
+## Terminology
- **Master Branch** - Must be named "master", must always have passing tests,
and is not guaranteed to always work in production environments.
@@ -54,184 +51,183 @@ Terminology
- **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)
--------------------------------------------
+## 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. Do not break the master branch.
- 2. A release is a git tag.
+ 1. Do not 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.
- 3. 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.
- 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.
+ 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.
+ 3. 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.
+ 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.
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.
+ 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, it is RECOMMENDED you create a pull request and discuss the
- changes with others there. This leaves a clear and visible history of
- how, when, and why the code looks and behaves the way it does.
+ 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, it is RECOMMENDED you create a pull request and discuss the
+ changes with others there. This leaves a clear and visible history of
+ how, when, and why the code looks and behaves the way it does.
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 (