mirror of
https://github.com/jimeh/commonflow.org.git
synced 2026-02-19 05:46:40 +00:00
wip: anchor links on every spec clause
This commit is contained in:
@@ -8,7 +8,7 @@
|
||||
document.documentElement.classList.add("dark");
|
||||
}
|
||||
})();
|
||||
</script><link rel="stylesheet" href="/_astro/index.Ds9Y8AeZ.css"></head> <body class="min-h-screen"> <div class="flex flex-col items-center justify-center min-h-screen p-8"> <div class="text-center"> <h1 class="text-[8rem] sm:text-[12rem] font-display font-bold leading-none
|
||||
</script><link rel="stylesheet" href="/_astro/index.Dj4jDMY1.css"></head> <body class="min-h-screen"> <div class="flex flex-col items-center justify-center min-h-screen p-8"> <div class="text-center"> <h1 class="text-[8rem] sm:text-[12rem] font-display font-bold leading-none
|
||||
text-gray-300 dark:text-neutral-700">
|
||||
404
|
||||
</h1> <p class="text-xl mb-2 text-gray-600 dark:text-neutral-400">
|
||||
|
||||
1
docs/_astro/index.Dj4jDMY1.css
Normal file
1
docs/_astro/index.Dj4jDMY1.css
Normal file
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
140
docs/index.html
140
docs/index.html
File diff suppressed because one or more lines are too long
@@ -8,7 +8,7 @@
|
||||
document.documentElement.classList.add("dark");
|
||||
}
|
||||
})();
|
||||
</script><link rel="stylesheet" href="/_astro/index.Ds9Y8AeZ.css"></head> <body class="min-h-screen"> <header id="site-header" class="fixed top-0 inset-x-0 z-50 border-b border-transparent
|
||||
</script><link rel="stylesheet" href="/_astro/index.Dj4jDMY1.css"></head> <body class="min-h-screen"> <header id="site-header" class="fixed top-0 inset-x-0 z-50 border-b border-transparent
|
||||
translate-y-[-100%] transition-transform duration-300
|
||||
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"> <!-- Logo / Title + Version --> <div class="flex items-center gap-3"> <a href="#hero" class="flex items-center gap-3 no-underline
|
||||
text-gray-950 dark:text-neutral-50
|
||||
@@ -162,7 +162,7 @@ License
|
||||
lg:pr-8 lg:mr-8 lg:border-r border-gray-200 dark:border-neutral-800"> <nav class="space-y-1 py-2"> <div class="text-xs font-semibold uppercase tracking-wider mb-4
|
||||
text-gray-500 dark:text-neutral-500">
|
||||
Table of Contents
|
||||
</div> <a href="#terminology" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-sidebar-link data-section-id="terminology"> <span>Terminology</span> </a><a href="#specification" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-sidebar-link data-section-id="specification"> <span>Specification</span> </a><a href="#spec-the-master-branch" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-the-master-branch"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 1. </span> <span>The Master Branch</span> </a><a href="#spec-changes" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-changes"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 2. </span> <span>Changes</span> </a><a href="#spec-git-best-practices" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-git-best-practices"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 3. </span> <span>Git Best Practices</span> </a><a href="#spec-versioning" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-versioning"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 4. </span> <span>Versioning</span> </a><a href="#spec-releases" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-releases"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 5. </span> <span>Releases</span> </a><a href="#spec-bug-fixes-rollback" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-bug-fixes-rollback"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 6. </span> <span>Bug Fixes & Rollback</span> </a><a href="#spec-maintenance-releases" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-maintenance-releases"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 7. </span> <span>Maintenance Releases</span> </a> </nav> </aside> <!-- Mobile floating button --> <button id="spec-toc-toggle" class="lg:hidden fixed bottom-6 right-6 z-40
|
||||
</div> <a href="#terminology" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-sidebar-link data-section-id="terminology"> <span>Terminology</span> </a><a href="#specification" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-sidebar-link data-section-id="specification"> <span>Specification</span> </a><a href="#clause-1" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-1"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 1. </span> <span>The Master Branch</span> </a><a href="#clause-2" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-2"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 2. </span> <span>Changes</span> </a><a href="#clause-3" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-3"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 3. </span> <span>Git Best Practices</span> </a><a href="#clause-4" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-4"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 4. </span> <span>Versioning</span> </a><a href="#clause-5" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-5"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 5. </span> <span>Releases</span> </a><a href="#clause-6" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-6"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 6. </span> <span>Bug Fixes & Rollback</span> </a><a href="#clause-7" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-7"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 7. </span> <span>Maintenance Releases</span> </a> </nav> </aside> <!-- Mobile floating button --> <button id="spec-toc-toggle" class="lg:hidden fixed bottom-6 right-6 z-40
|
||||
w-12 h-12 rounded-full shadow-lg
|
||||
bg-sky-600 text-white
|
||||
flex items-center justify-center
|
||||
@@ -172,7 +172,7 @@ Table of Contents
|
||||
rounded-t-2xl shadow-xl p-6"> <div class="flex items-center justify-between mb-4"> <span class="text-sm font-semibold uppercase tracking-wider
|
||||
text-gray-500 dark:text-neutral-500">
|
||||
Jump to Section
|
||||
</span> <button class="p-2 rounded-lg hover:bg-gray-100 dark:hover:bg-neutral-800" data-toc-close aria-label="Close"> <svg width="1em" height="1em" class="w-5 h-5" data-icon="heroicons:x-mark"> <symbol id="ai:heroicons:x-mark" viewBox="0 0 24 24"><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M6 18L18 6M6 6l12 12"/></symbol><use href="#ai:heroicons:x-mark"></use> </svg> </button> </div> <nav class="space-y-1"> <a href="#terminology" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-toc-link> <span>Terminology</span> </a><a href="#specification" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-toc-link> <span>Specification</span> </a><a href="#spec-the-master-branch" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 1. </span> <span>The Master Branch</span> </a><a href="#spec-changes" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 2. </span> <span>Changes</span> </a><a href="#spec-git-best-practices" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 3. </span> <span>Git Best Practices</span> </a><a href="#spec-versioning" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 4. </span> <span>Versioning</span> </a><a href="#spec-releases" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 5. </span> <span>Releases</span> </a><a href="#spec-bug-fixes-rollback" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 6. </span> <span>Bug Fixes & Rollback</span> </a><a href="#spec-maintenance-releases" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 7. </span> <span>Maintenance Releases</span> </a> </nav> </div> </div> <script type="module" src="/_astro/SpecSidebar.astro_astro_type_script_index_0_lang.BQBj5HuJ.js"></script> </div> <!-- Main content --> <div class="flex-1 min-w-0"> <article class="prose-spec"> <!-- Terminology --> <section id="terminology"> <h2>Terminology</h2> <ul>
|
||||
</span> <button class="p-2 rounded-lg hover:bg-gray-100 dark:hover:bg-neutral-800" data-toc-close aria-label="Close"> <svg width="1em" height="1em" class="w-5 h-5" data-icon="heroicons:x-mark"> <symbol id="ai:heroicons:x-mark" viewBox="0 0 24 24"><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M6 18L18 6M6 6l12 12"/></symbol><use href="#ai:heroicons:x-mark"></use> </svg> </button> </div> <nav class="space-y-1"> <a href="#terminology" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-toc-link> <span>Terminology</span> </a><a href="#specification" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-toc-link> <span>Specification</span> </a><a href="#clause-1" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 1. </span> <span>The Master Branch</span> </a><a href="#clause-2" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 2. </span> <span>Changes</span> </a><a href="#clause-3" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 3. </span> <span>Git Best Practices</span> </a><a href="#clause-4" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 4. </span> <span>Versioning</span> </a><a href="#clause-5" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 5. </span> <span>Releases</span> </a><a href="#clause-6" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 6. </span> <span>Bug Fixes & Rollback</span> </a><a href="#clause-7" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 7. </span> <span>Maintenance Releases</span> </a> </nav> </div> </div> <script type="module" src="/_astro/SpecSidebar.astro_astro_type_script_index_0_lang.BQBj5HuJ.js"></script> </div> <!-- Main content --> <div class="flex-1 min-w-0"> <article class="prose-spec"> <!-- Terminology --> <section id="terminology"> <h2>Terminology</h2> <ul>
|
||||
<li><strong>Master Branch</strong> - Must always have passing tests, is considered bleeding
|
||||
edge, and must be named <code>master</code>.</li>
|
||||
<li><strong>Change Branches</strong> - Any branch that introduces changes like a new feature, a
|
||||
@@ -198,136 +198,136 @@ branch.</li>
|
||||
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
|
||||
interpreted as described in <a href="https://tools.ietf.org/html/rfc2119">RFC 2119</a>.</p>
|
||||
<ol>
|
||||
<li id="spec-the-master-branch">The Master Branch
|
||||
<li id="clause-1"><a href="#clause-1" class="clause-link" aria-hidden="true"></a>The Master Branch
|
||||
<ol>
|
||||
<li>A branch named "master" MUST exist and it MUST be referred to as the
|
||||
<li id="clause-1-1"><a href="#clause-1-1" class="clause-link" aria-hidden="true"></a>A branch named "master" MUST exist and it MUST be referred to as the
|
||||
"master branch".</li>
|
||||
<li>The master branch MUST be considered bleeding edge.</li>
|
||||
<li>The master branch MUST always be in a non-broken state with its test
|
||||
<li id="clause-1-2"><a href="#clause-1-2" class="clause-link" aria-hidden="true"></a>The master branch MUST be considered bleeding edge.</li>
|
||||
<li id="clause-1-3"><a href="#clause-1-3" class="clause-link" aria-hidden="true"></a>The master branch MUST always be in a non-broken state with its test
|
||||
suite passing.</li>
|
||||
<li>The master branch SHOULD always be in a "as near as possible ready for
|
||||
<li id="clause-1-4"><a href="#clause-1-4" class="clause-link" aria-hidden="true"></a>The master branch SHOULD always be in a "as near as possible ready for
|
||||
release/production" state to reduce the friction of creating a new
|
||||
release.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-changes">Changes
|
||||
<li id="clause-2"><a href="#clause-2" class="clause-link" aria-hidden="true"></a>Changes
|
||||
<ol>
|
||||
<li>Changes MUST be performed on a separate branch that SHOULD be referred to
|
||||
<li id="clause-2-1"><a href="#clause-2-1" class="clause-link" aria-hidden="true"></a>Changes MUST be performed on a separate branch that SHOULD be referred to
|
||||
as a "change branch". All change branches MUST have descriptive names. It
|
||||
is RECOMMENDED that you commit often locally, and you SHOULD regularly
|
||||
push your work to the same named branch on the remote server.</li>
|
||||
<li>When a change branch is created, the branch that it is created from
|
||||
<li id="clause-2-2"><a href="#clause-2-2" class="clause-link" aria-hidden="true"></a>When a change branch is created, the branch that it is created from
|
||||
SHOULD be referred to as the "source branch". Each change branch also
|
||||
needs a designated "merge target branch", typically this will be the same
|
||||
as the source branch.</li>
|
||||
<li>Change branches MUST be regularly updated with any changes from their
|
||||
<li id="clause-2-3"><a href="#clause-2-3" class="clause-link" aria-hidden="true"></a>Change branches MUST be regularly updated with any changes from their
|
||||
source branch. This MUST be done by rebasing the change branch on top of
|
||||
the source branch. To be clear you MUST NOT merge a source branch into a
|
||||
change branch.</li>
|
||||
<li>After rebasing a change branch on top of its source branch you MUST push
|
||||
<li id="clause-2-4"><a href="#clause-2-4" class="clause-link" aria-hidden="true"></a>After rebasing a change branch on top of its source branch you MUST push
|
||||
the change branch to the remote server. This will require you do a force
|
||||
push, and you SHOULD use the "--force-with-lease" git push option.</li>
|
||||
<li>To merge a change branch into its merge target branch, you MUST open a
|
||||
<li id="clause-2-5"><a href="#clause-2-5" class="clause-link" aria-hidden="true"></a>To merge a change branch into its merge target branch, you MUST open a
|
||||
"pull request" (or equivalent) so others can review and approve your
|
||||
changes.</li>
|
||||
<li>A pull request MUST only be merged when the change branch is up-to-date
|
||||
<li id="clause-2-6"><a href="#clause-2-6" class="clause-link" aria-hidden="true"></a>A pull request MUST only be merged when the change branch is up-to-date
|
||||
with its source branch, the test suite is passing, and you and others are
|
||||
happy with the change. This is especially important if the merge target
|
||||
is the master branch.</li>
|
||||
<li>To get feedback, help, or generally just discuss a change branch with
|
||||
<li id="clause-2-7"><a href="#clause-2-7" class="clause-link" aria-hidden="true"></a>To get feedback, help, or generally just discuss a change branch with
|
||||
others, it is RECOMMENDED you do this by creating a pull request and
|
||||
discuss the changes with others there.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-git-best-practices">Git Best Practices
|
||||
<li id="clause-3"><a href="#clause-3" class="clause-link" aria-hidden="true"></a>Git Best Practices
|
||||
<ol>
|
||||
<li>All commit messages SHOULD follow the Commit Guidelines and format from
|
||||
<li id="clause-3-1"><a href="#clause-3-1" class="clause-link" aria-hidden="true"></a>All commit messages SHOULD follow the Commit Guidelines and format from
|
||||
the official git
|
||||
documentation:
|
||||
<a href="https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project">https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project</a></li>
|
||||
<li>You SHOULD always use "--force-with-lease" when doing a force push. The
|
||||
<li id="clause-3-2"><a href="#clause-3-2" class="clause-link" aria-hidden="true"></a>You SHOULD always use "--force-with-lease" when doing a force push. The
|
||||
plain "--force" option is dangerous and destructive. More
|
||||
information:
|
||||
<a href="https://developer.atlassian.com/blog/2015/04/force-with-lease/">https://developer.atlassian.com/blog/2015/04/force-with-lease/</a></li>
|
||||
<li>You SHOULD understand and be comfortable with
|
||||
<li id="clause-3-3"><a href="#clause-3-3" class="clause-link" aria-hidden="true"></a>You SHOULD understand and be comfortable with
|
||||
rebasing: <a href="https://git-scm.com/book/en/v2/Git-Branching-Rebasing">https://git-scm.com/book/en/v2/Git-Branching-Rebasing</a></li>
|
||||
<li>It is RECOMMENDED that you always do "git pull --rebase" instead of "git
|
||||
<li id="clause-3-4"><a href="#clause-3-4" class="clause-link" aria-hidden="true"></a>It is RECOMMENDED that you always do "git pull --rebase" instead of "git
|
||||
pull" to avoid unnecessary merge commits. You can make this the default
|
||||
behavior of "git pull" with "git config --global pull.rebase true".</li>
|
||||
<li>It is RECOMMENDED that all branches be merged using "git merge --no-ff".
|
||||
<li id="clause-3-5"><a href="#clause-3-5" class="clause-link" aria-hidden="true"></a>It is RECOMMENDED that all branches be merged using "git merge --no-ff".
|
||||
This makes sure the reference to the original branch is kept in the commits,
|
||||
allows one to revert a merge by reverting a single merge commit, and creates
|
||||
a merge commit to mark the integration of the branch with master.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-versioning">Versioning
|
||||
<li id="clause-4"><a href="#clause-4" class="clause-link" aria-hidden="true"></a>Versioning
|
||||
<ol>
|
||||
<li>The project MUST have its version hard-coded somewhere in the
|
||||
<li id="clause-4-1"><a href="#clause-4-1" class="clause-link" aria-hidden="true"></a>The project MUST have its version hard-coded somewhere in the
|
||||
code-base. It is RECOMMENDED that this is done in a file called "VERSION"
|
||||
located in the root of the project.</li>
|
||||
<li>If you are using a "VERSION" file in the root of the project, this MUST
|
||||
<li id="clause-4-2"><a href="#clause-4-2" class="clause-link" aria-hidden="true"></a>If you are using a "VERSION" file in the root of the project, this MUST
|
||||
only contain the exact version string.</li>
|
||||
<li>The version string SHOULD follow the Semantic Versioning
|
||||
<li id="clause-4-3"><a href="#clause-4-3" class="clause-link" aria-hidden="true"></a>The version string SHOULD follow the Semantic Versioning
|
||||
(<a href="http://semver.org/">http://semver.org/</a>) format. Use of Semantic Versioning is OPTIONAL,
|
||||
but the version string MUST NOT have a "v" prefix. For example "v2.11.4"
|
||||
is bad, and "2.11.4" is good.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-releases">Releases
|
||||
<li id="clause-5"><a href="#clause-5" class="clause-link" aria-hidden="true"></a>Releases
|
||||
<ol>
|
||||
<li>To create a new release, you MUST create a "version bump" commit directly
|
||||
<li id="clause-5-1"><a href="#clause-5-1" class="clause-link" aria-hidden="true"></a>To create a new release, you MUST create a "version bump" commit directly
|
||||
on the master branch which changes the hard-coded version value of the
|
||||
project. The version bump commit MUST have a git tag created on it and
|
||||
named as the exact version string.</li>
|
||||
<li>A version bump commit MUST have a commit message title of "Bump version
|
||||
<li id="clause-5-2"><a href="#clause-5-2" class="clause-link" aria-hidden="true"></a>A version bump commit MUST have a commit message title of "Bump version
|
||||
to VERSION". For example, if the new version string is "2.11.4", the
|
||||
first line of the commit message MUST read: "Bump version to 2.11.4"</li>
|
||||
<li>The release tag on the version bump commit MUST be named exactly the same
|
||||
<li id="clause-5-3"><a href="#clause-5-3" class="clause-link" aria-hidden="true"></a>The release tag on the version bump commit MUST be named exactly the same
|
||||
as the version string. The tag name can OPTIONALLY be prefixed with
|
||||
"v". For example the tag name can be either "2.11.4" or "v2.11.4".</li>
|
||||
<li>It is RECOMMENDED that release tags are lightweight tags, but you can
|
||||
<li id="clause-5-4"><a href="#clause-5-4" class="clause-link" aria-hidden="true"></a>It is RECOMMENDED that release tags are lightweight tags, but you can
|
||||
OPTIONALLY use annotated tags if you want to include changelog
|
||||
information in the release tag itself.</li>
|
||||
<li>If you use annotated release tags, the first line of the annotation MUST
|
||||
<li id="clause-5-5"><a href="#clause-5-5" class="clause-link" aria-hidden="true"></a>If you use annotated release tags, the first line of the annotation MUST
|
||||
read "Release VERSION". For example for version "2.11.4" the first line
|
||||
of the tag annotation would read "Release 2.11.4". The second line must
|
||||
be blank, and the changelog MUST start on the third line.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-bug-fixes-rollback">Bug Fixes & Rollback
|
||||
<li id="clause-6"><a href="#clause-6" class="clause-link" aria-hidden="true"></a>Bug Fixes & Rollback
|
||||
<ol>
|
||||
<li>You MUST NOT under any circumstances force push to the master branch.</li>
|
||||
<li>If a change branch which has been merged in to the master branch is found
|
||||
<li id="clause-6-1"><a href="#clause-6-1" class="clause-link" aria-hidden="true"></a>You MUST NOT under any circumstances force push to the master branch.</li>
|
||||
<li id="clause-6-2"><a href="#clause-6-2" class="clause-link" aria-hidden="true"></a>If a change branch which has been merged in to the master branch is found
|
||||
to have a bug in it, the bug fix work MUST be done as a new separate
|
||||
change branch and MUST follow the same workflow as any other change
|
||||
branch.</li>
|
||||
<li>If a change branch is wrongfully merged in to master, or for any other
|
||||
<li id="clause-6-3"><a href="#clause-6-3" class="clause-link" aria-hidden="true"></a>If a change branch is wrongfully merged in to master, or for any other
|
||||
reason the merge must be undone, you MUST undo the merge by reverting the
|
||||
merge commit itself. Effectively creating a new commit that reverses all
|
||||
the relevant changes.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-maintenance-releases">Maintenance Releases
|
||||
<li id="clause-7"><a href="#clause-7" class="clause-link" aria-hidden="true"></a>Maintenance Releases
|
||||
<ol>
|
||||
<li>Any branch that has a name starting with "stable-" SHOULD be referred to
|
||||
<li id="clause-7-1"><a href="#clause-7-1" class="clause-link" aria-hidden="true"></a>Any branch that has a name starting with "stable-" SHOULD be referred to
|
||||
as a "maintenance branch".</li>
|
||||
<li>Maintenance branches are used for managing new releases of older
|
||||
<li id="clause-7-2"><a href="#clause-7-2" class="clause-link" aria-hidden="true"></a>Maintenance branches are used for managing new releases of older
|
||||
versions. Typically this is used to provide security updates for older
|
||||
versions when the master branch has moved on to a point that a new
|
||||
release for the old version cannot be made from the master branch.</li>
|
||||
<li>A "maintenance release" is identical to a regular release, except the
|
||||
<li id="clause-7-3"><a href="#clause-7-3" class="clause-link" aria-hidden="true"></a>A "maintenance release" is identical to a regular release, except the
|
||||
version bump commit and the release tag are placed on the maintenance
|
||||
branch instead of on the master branch.</li>
|
||||
<li>A maintenance branch SHOULD follow a "stable-X.Y" naming pattern, where
|
||||
<li id="clause-7-4"><a href="#clause-7-4" class="clause-link" aria-hidden="true"></a>A maintenance branch SHOULD follow a "stable-X.Y" naming pattern, where
|
||||
"X" is the MAJOR version and "Y" is the minor version.</li>
|
||||
<li>A maintenance branch MUST be created from the relevant release tag. For
|
||||
<li id="clause-7-5"><a href="#clause-7-5" class="clause-link" aria-hidden="true"></a>A maintenance branch MUST be created from the relevant release tag. For
|
||||
example if there is a security fix for all 2.9.x releases, the latest of
|
||||
which is "2.9.7", we create a new branch called "stable-2.9" off of the
|
||||
"2.9.7" release tag. The security fix release will then end up being
|
||||
version "2.9.8".</li>
|
||||
<li>When working on a maintenance release, the relevant maintenance branch
|
||||
<li id="clause-7-6"><a href="#clause-7-6" class="clause-link" aria-hidden="true"></a>When working on a maintenance release, the relevant maintenance branch
|
||||
MUST be thought of as the master branch for that maintenance work.</li>
|
||||
<li>Changes in a maintenance branch SHOULD typically come from work being
|
||||
<li id="clause-7-7"><a href="#clause-7-7" class="clause-link" aria-hidden="true"></a>Changes in a maintenance branch SHOULD typically come from work being
|
||||
done against the master branch. Meaning changes SHOULD only trickle
|
||||
downwards from the master branch. If a change needs to trickle back up
|
||||
into the master branch, that work should have happened against the master
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
document.documentElement.classList.add("dark");
|
||||
}
|
||||
})();
|
||||
</script><link rel="stylesheet" href="/_astro/index.Ds9Y8AeZ.css"></head> <body class="min-h-screen"> <header id="site-header" class="fixed top-0 inset-x-0 z-50 border-b border-transparent
|
||||
</script><link rel="stylesheet" href="/_astro/index.Dj4jDMY1.css"></head> <body class="min-h-screen"> <header id="site-header" class="fixed top-0 inset-x-0 z-50 border-b border-transparent
|
||||
translate-y-[-100%] transition-transform duration-300
|
||||
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"> <!-- Logo / Title + Version --> <div class="flex items-center gap-3"> <a href="#hero" class="flex items-center gap-3 no-underline
|
||||
text-gray-950 dark:text-neutral-50
|
||||
@@ -162,7 +162,7 @@ License
|
||||
lg:pr-8 lg:mr-8 lg:border-r border-gray-200 dark:border-neutral-800"> <nav class="space-y-1 py-2"> <div class="text-xs font-semibold uppercase tracking-wider mb-4
|
||||
text-gray-500 dark:text-neutral-500">
|
||||
Table of Contents
|
||||
</div> <a href="#terminology" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-sidebar-link data-section-id="terminology"> <span>Terminology</span> </a><a href="#specification" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-sidebar-link data-section-id="specification"> <span>Specification</span> </a><a href="#spec-the-master-branch" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-the-master-branch"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 1. </span> <span>The Master Branch</span> </a><a href="#spec-change-branches" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-change-branches"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 2. </span> <span>Change Branches</span> </a><a href="#spec-pull-requests" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-pull-requests"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 3. </span> <span>Pull Requests</span> </a><a href="#spec-versioning" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-versioning"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 4. </span> <span>Versioning</span> </a><a href="#spec-releases" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-releases"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 5. </span> <span>Releases</span> </a><a href="#spec-release-branches" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-release-branches"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 6. </span> <span>Release Branches</span> </a><a href="#spec-bug-fixes-rollback" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-bug-fixes-rollback"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 7. </span> <span>Bug Fixes & Rollback</span> </a><a href="#spec-git-best-practices" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-git-best-practices"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 8. </span> <span>Git Best Practices</span> </a> </nav> </aside> <!-- Mobile floating button --> <button id="spec-toc-toggle" class="lg:hidden fixed bottom-6 right-6 z-40
|
||||
</div> <a href="#terminology" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-sidebar-link data-section-id="terminology"> <span>Terminology</span> </a><a href="#specification" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-sidebar-link data-section-id="specification"> <span>Specification</span> </a><a href="#clause-1" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-1"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 1. </span> <span>The Master Branch</span> </a><a href="#clause-2" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-2"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 2. </span> <span>Change Branches</span> </a><a href="#clause-3" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-3"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 3. </span> <span>Pull Requests</span> </a><a href="#clause-4" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-4"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 4. </span> <span>Versioning</span> </a><a href="#clause-5" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-5"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 5. </span> <span>Releases</span> </a><a href="#clause-6" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-6"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 6. </span> <span>Release Branches</span> </a><a href="#clause-7" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-7"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 7. </span> <span>Bug Fixes & Rollback</span> </a><a href="#clause-8" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-8"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 8. </span> <span>Git Best Practices</span> </a> </nav> </aside> <!-- Mobile floating button --> <button id="spec-toc-toggle" class="lg:hidden fixed bottom-6 right-6 z-40
|
||||
w-12 h-12 rounded-full shadow-lg
|
||||
bg-sky-600 text-white
|
||||
flex items-center justify-center
|
||||
@@ -172,7 +172,7 @@ Table of Contents
|
||||
rounded-t-2xl shadow-xl p-6"> <div class="flex items-center justify-between mb-4"> <span class="text-sm font-semibold uppercase tracking-wider
|
||||
text-gray-500 dark:text-neutral-500">
|
||||
Jump to Section
|
||||
</span> <button class="p-2 rounded-lg hover:bg-gray-100 dark:hover:bg-neutral-800" data-toc-close aria-label="Close"> <svg width="1em" height="1em" class="w-5 h-5" data-icon="heroicons:x-mark"> <symbol id="ai:heroicons:x-mark" viewBox="0 0 24 24"><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M6 18L18 6M6 6l12 12"/></symbol><use href="#ai:heroicons:x-mark"></use> </svg> </button> </div> <nav class="space-y-1"> <a href="#terminology" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-toc-link> <span>Terminology</span> </a><a href="#specification" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-toc-link> <span>Specification</span> </a><a href="#spec-the-master-branch" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 1. </span> <span>The Master Branch</span> </a><a href="#spec-change-branches" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 2. </span> <span>Change Branches</span> </a><a href="#spec-pull-requests" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 3. </span> <span>Pull Requests</span> </a><a href="#spec-versioning" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 4. </span> <span>Versioning</span> </a><a href="#spec-releases" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 5. </span> <span>Releases</span> </a><a href="#spec-release-branches" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 6. </span> <span>Release Branches</span> </a><a href="#spec-bug-fixes-rollback" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 7. </span> <span>Bug Fixes & Rollback</span> </a><a href="#spec-git-best-practices" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 8. </span> <span>Git Best Practices</span> </a> </nav> </div> </div> <script type="module" src="/_astro/SpecSidebar.astro_astro_type_script_index_0_lang.BQBj5HuJ.js"></script> </div> <!-- Main content --> <div class="flex-1 min-w-0"> <article class="prose-spec"> <!-- Terminology --> <section id="terminology"> <h2>Terminology</h2> <ul>
|
||||
</span> <button class="p-2 rounded-lg hover:bg-gray-100 dark:hover:bg-neutral-800" data-toc-close aria-label="Close"> <svg width="1em" height="1em" class="w-5 h-5" data-icon="heroicons:x-mark"> <symbol id="ai:heroicons:x-mark" viewBox="0 0 24 24"><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M6 18L18 6M6 6l12 12"/></symbol><use href="#ai:heroicons:x-mark"></use> </svg> </button> </div> <nav class="space-y-1"> <a href="#terminology" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-toc-link> <span>Terminology</span> </a><a href="#specification" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-toc-link> <span>Specification</span> </a><a href="#clause-1" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 1. </span> <span>The Master Branch</span> </a><a href="#clause-2" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 2. </span> <span>Change Branches</span> </a><a href="#clause-3" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 3. </span> <span>Pull Requests</span> </a><a href="#clause-4" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 4. </span> <span>Versioning</span> </a><a href="#clause-5" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 5. </span> <span>Releases</span> </a><a href="#clause-6" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 6. </span> <span>Release Branches</span> </a><a href="#clause-7" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 7. </span> <span>Bug Fixes & Rollback</span> </a><a href="#clause-8" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 8. </span> <span>Git Best Practices</span> </a> </nav> </div> </div> <script type="module" src="/_astro/SpecSidebar.astro_astro_type_script_index_0_lang.BQBj5HuJ.js"></script> </div> <!-- Main content --> <div class="flex-1 min-w-0"> <article class="prose-spec"> <!-- Terminology --> <section id="terminology"> <h2>Terminology</h2> <ul>
|
||||
<li><strong>Master Branch</strong> - Must always have passing tests, is considered bleeding
|
||||
edge, and must be named <code>master</code>.</li>
|
||||
<li><strong>Change Branches</strong> - Any branch that introduces changes like a new feature, a
|
||||
@@ -193,134 +193,134 @@ also for long-term maintenance of older version.</li>
|
||||
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
|
||||
interpreted as described in <a href="https://tools.ietf.org/html/rfc2119">RFC 2119</a>.</p>
|
||||
<ol>
|
||||
<li id="spec-the-master-branch">The Master Branch
|
||||
<li id="clause-1"><a href="#clause-1" class="clause-link" aria-hidden="true"></a>The Master Branch
|
||||
<ol>
|
||||
<li>A branch named "master" MUST exist and it MUST be referred to as the
|
||||
<li id="clause-1-1"><a href="#clause-1-1" class="clause-link" aria-hidden="true"></a>A branch named "master" MUST exist and it MUST be referred to as the
|
||||
"master branch".</li>
|
||||
<li>The master branch MUST be considered bleeding edge.</li>
|
||||
<li>The master branch MUST always be in a non-broken state with its test
|
||||
<li id="clause-1-2"><a href="#clause-1-2" class="clause-link" aria-hidden="true"></a>The master branch MUST be considered bleeding edge.</li>
|
||||
<li id="clause-1-3"><a href="#clause-1-3" class="clause-link" aria-hidden="true"></a>The master branch MUST always be in a non-broken state with its test
|
||||
suite passing.</li>
|
||||
<li>The master branch SHOULD always be in a "as near as possibly ready for
|
||||
<li id="clause-1-4"><a href="#clause-1-4" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-change-branches">Change Branches
|
||||
<li id="clause-2"><a href="#clause-2" class="clause-link" aria-hidden="true"></a>Change Branches
|
||||
<ol>
|
||||
<li>Each change (feature, bugfix, etc.) MUST be performed on separate
|
||||
<li id="clause-2-1"><a href="#clause-2-1" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
<li>You MUST create separate change branches for each distinctly different
|
||||
<li id="clause-2-2"><a href="#clause-2-2" class="clause-link" aria-hidden="true"></a>You MUST create separate change branches for each distinctly different
|
||||
change. You MUST NOT include multiple unrelated changes into a single
|
||||
change branch.</li>
|
||||
<li>When a change branch is created, the branch that it is created from
|
||||
<li id="clause-2-3"><a href="#clause-2-3" class="clause-link" aria-hidden="true"></a>When a change branch is created, the branch that it is created from
|
||||
SHOULD be referred to as the "source branch". Each change branch also
|
||||
needs a designated "merge target" branch, typically this will be the same
|
||||
as the source branch.</li>
|
||||
<li>Change branches MUST be regularly updated with any changes from their
|
||||
<li id="clause-2-4"><a href="#clause-2-4" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
<li>After rebasing a change branch on top of its source branch you MUST push
|
||||
<li id="clause-2-5"><a href="#clause-2-5" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-pull-requests">Pull Requests
|
||||
<li id="clause-3"><a href="#clause-3" class="clause-link" aria-hidden="true"></a>Pull Requests
|
||||
<ol>
|
||||
<li>To merge a change branch into its merge target, you MUST open a "pull
|
||||
<li id="clause-3-1"><a href="#clause-3-1" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
<li>A pull request MUST only be merged when the change branch is up-to-date
|
||||
<li id="clause-3-2"><a href="#clause-3-2" class="clause-link" aria-hidden="true"></a>A pull request MUST only be merged when the change branch is up-to-date
|
||||
with its source branch, the test suite is passing, and you and others are
|
||||
happy with the change. This is especially important if the merge target
|
||||
is the master branch.</li>
|
||||
<li>To get feedback, help, or generally just discuss a change branch with
|
||||
<li id="clause-3-3"><a href="#clause-3-3" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-versioning">Versioning
|
||||
<li id="clause-4"><a href="#clause-4" class="clause-link" aria-hidden="true"></a>Versioning
|
||||
<ol>
|
||||
<li>The project MUST have its version hard-coded somewhere in the
|
||||
<li id="clause-4-1"><a href="#clause-4-1" class="clause-link" aria-hidden="true"></a>The project MUST have its version hard-coded somewhere in the
|
||||
code-base. It is RECOMMENDED that this is done in a file called "VERSION"
|
||||
located in the root of the project.</li>
|
||||
<li>If you are using a "VERSION" file in the root of the project, this MUST
|
||||
<li id="clause-4-2"><a href="#clause-4-2" class="clause-link" aria-hidden="true"></a>If you are using a "VERSION" file in the root of the project, this MUST
|
||||
only contain the exact version string.</li>
|
||||
<li>The version string SHOULD follow the Semantic Versioning
|
||||
<li id="clause-4-3"><a href="#clause-4-3" class="clause-link" aria-hidden="true"></a>The version string SHOULD follow the Semantic Versioning
|
||||
(<a href="http://semver.org/">http://semver.org/</a>) format. Use of Semantic Versioning is OPTIONAL,
|
||||
but the version string MUST NOT have a "v" prefix. For example "v2.11.4"
|
||||
is bad, and "2.11.4" is good.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-releases">Releases
|
||||
<li id="clause-5"><a href="#clause-5" class="clause-link" aria-hidden="true"></a>Releases
|
||||
<ol>
|
||||
<li>To create a new release, you MUST create a "version bump" commit which
|
||||
<li id="clause-5-1"><a href="#clause-5-1" class="clause-link" aria-hidden="true"></a>To create a new release, you MUST create a "version bump" commit which
|
||||
changes the hard-coded version string of the project. The version bump
|
||||
commit MUST have a git tag created on it and named as the exact version
|
||||
string.</li>
|
||||
<li>If you are not using a release branch, then the version bump commit MUST
|
||||
<li id="clause-5-2"><a href="#clause-5-2" class="clause-link" aria-hidden="true"></a>If you are not using a release branch, then the version bump commit MUST
|
||||
be created directly on the master branch.</li>
|
||||
<li>The version bump commit MUST have a commit message title of "Bump version
|
||||
<li id="clause-5-3"><a href="#clause-5-3" class="clause-link" aria-hidden="true"></a>The version bump commit MUST have a commit message title of "Bump version
|
||||
to VERSION". For example, if the new version string is "2.11.4", the
|
||||
first line of the commit message MUST read: "Bump version to 2.11.4"</li>
|
||||
<li>The release tag on the version bump commit MUST be named exactly the same
|
||||
<li id="clause-5-4"><a href="#clause-5-4" class="clause-link" aria-hidden="true"></a>The release tag on the version bump commit MUST be named exactly the same
|
||||
as the version string. The tag name can OPTIONALLY be prefixed with
|
||||
"v". For example the tag name can be either "2.11.4" or "v2.11.4". You
|
||||
MUST not use a mix of "v" prefixed and non-prefixed tags. Pick one form
|
||||
and stick to it.</li>
|
||||
<li>It is RECOMMENDED that release tags are lightweight tags, but you can
|
||||
<li id="clause-5-5"><a href="#clause-5-5" class="clause-link" aria-hidden="true"></a>It is RECOMMENDED that release tags are lightweight tags, but you can
|
||||
OPTIONALLY use annotated tags if you want to include changelog
|
||||
information in the release tag itself.</li>
|
||||
<li>If you use annotated release tags, the first line of the annotation MUST
|
||||
<li id="clause-5-6"><a href="#clause-5-6" class="clause-link" aria-hidden="true"></a>If you use annotated release tags, the first line of the annotation MUST
|
||||
read "Release VERSION". For example for version "2.11.4" the first line
|
||||
of the tag annotation would read "Release 2.11.4". The second line must
|
||||
be blank, and the changelog MUST start on the third line.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-release-branches">Release Branches
|
||||
<li id="clause-6"><a href="#clause-6" class="clause-link" aria-hidden="true"></a>Release Branches
|
||||
<ol>
|
||||
<li>Any branch that has a name starting with "release-" SHOULD be referred to
|
||||
<li id="clause-6-1"><a href="#clause-6-1" class="clause-link" aria-hidden="true"></a>Any branch that has a name starting with "release-" SHOULD be referred to
|
||||
as a "release branch".</li>
|
||||
<li>Use of release branches is OPTIONAL.</li>
|
||||
<li>Changes in a release branch SHOULD typically come from work being
|
||||
<li id="clause-6-2"><a href="#clause-6-2" class="clause-link" aria-hidden="true"></a>Use of release branches is OPTIONAL.</li>
|
||||
<li id="clause-6-3"><a href="#clause-6-3" class="clause-link" aria-hidden="true"></a>Changes in a release branch SHOULD typically come from work being
|
||||
done against the master branch. Meaning changes SHOULD only trickle
|
||||
downwards from the master branch. If a change needs to trickle back up
|
||||
into the master branch, that work should have happened against the master
|
||||
branch in the first place. One exception to this is version bump commits.</li>
|
||||
<li>There are two types of release branches; short-term, and long-term.</li>
|
||||
<li>Short-Term Release Branches
|
||||
<li id="clause-6-4"><a href="#clause-6-4" class="clause-link" aria-hidden="true"></a>There are two types of release branches; short-term, and long-term.</li>
|
||||
<li id="clause-6-5"><a href="#clause-6-5" class="clause-link" aria-hidden="true"></a>Short-Term Release Branches
|
||||
<ol>
|
||||
<li>Used for creating a specific versioned release.</li>
|
||||
<li>A short-term release branch is RECOMMENDED if there is a lengthy
|
||||
<li id="clause-6-5-1"><a href="#clause-6-5-1" class="clause-link" aria-hidden="true"></a>Used for creating a specific versioned release.</li>
|
||||
<li id="clause-6-5-2"><a href="#clause-6-5-2" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
<li>MUST have a name of "release-VERSION". For example for version
|
||||
<li id="clause-6-5-3"><a href="#clause-6-5-3" class="clause-link" aria-hidden="true"></a>MUST have a name of "release-VERSION". For example for version
|
||||
"2.11.4" the release branch name MUST be "release-2.11.4".</li>
|
||||
<li>When using a short-term release branch, the version bump commit and
|
||||
<li id="clause-6-5-4"><a href="#clause-6-5-4" class="clause-link" aria-hidden="true"></a>When using a short-term release branch, the version bump commit and
|
||||
release tag MUST be made directly on the release branch itself.</li>
|
||||
<li>Only very minor changes should be performed on a short-term release
|
||||
<li id="clause-6-5-5"><a href="#clause-6-5-5" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
<li>After the version bump commit and release tag have been created, the
|
||||
<li id="clause-6-5-6"><a href="#clause-6-5-6" class="clause-link" aria-hidden="true"></a>After the version bump commit and release tag have been created, the
|
||||
release branch MUST be merged back into its source branch and then
|
||||
deleted. Typically the source branch will be the master branch.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Long-Term Release Branches
|
||||
<li id="clause-6-6"><a href="#clause-6-6" class="clause-link" aria-hidden="true"></a>Long-Term Release Branches
|
||||
<ol>
|
||||
<li>Used for work on versions which are not currently part of the master
|
||||
<li id="clause-6-6-1"><a href="#clause-6-6-1" class="clause-link" aria-hidden="true"></a>Used for work on versions which are not currently part of the master
|
||||
branch. Typically this is useful when you need to create a new
|
||||
maintenance release for a older version.</li>
|
||||
<li>The branch name MUST have a non-specific version number. For example
|
||||
<li id="clause-6-6-2"><a href="#clause-6-6-2" class="clause-link" aria-hidden="true"></a>The branch name MUST have a non-specific version number. For example
|
||||
a long-term release branch for creating new 2.9.x releases would be
|
||||
named "release-2.9".</li>
|
||||
<li>To create a new release from a long-term release branch, you MUST
|
||||
<li id="clause-6-6-3"><a href="#clause-6-6-3" class="clause-link" aria-hidden="true"></a>To create a new release from a long-term release branch, you MUST
|
||||
create a version bump commit and release tag directly on the release
|
||||
branch.</li>
|
||||
<li>A long-term release branch MUST be created from the relevant release
|
||||
<li id="clause-6-6-4"><a href="#clause-6-6-4" class="clause-link" aria-hidden="true"></a>A long-term release branch MUST be created from the relevant release
|
||||
tag. For example if the master branch is on version 2.11.4 and there
|
||||
is a security fix for all 2.9.x releases, the latest of which is
|
||||
"2.9.7". Create a new branch called "release-2.9" off of the "2.9.7"
|
||||
@@ -330,38 +330,38 @@ release tag. The security fix release will then end up being version
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-bug-fixes-rollback">Bug Fixes & Rollback
|
||||
<li id="clause-7"><a href="#clause-7" class="clause-link" aria-hidden="true"></a>Bug Fixes & Rollback
|
||||
<ol>
|
||||
<li>You MUST NOT under any circumstances force push to the master branch.</li>
|
||||
<li>If a change branch which has been merged into the master branch is found
|
||||
<li id="clause-7-1"><a href="#clause-7-1" class="clause-link" aria-hidden="true"></a>You MUST NOT under any circumstances force push to the master branch.</li>
|
||||
<li id="clause-7-2"><a href="#clause-7-2" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
<li>If a change branch is wrongfully merged into master, or for any other
|
||||
<li id="clause-7-3"><a href="#clause-7-3" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-git-best-practices">Git Best Practices
|
||||
<li id="clause-8"><a href="#clause-8" class="clause-link" aria-hidden="true"></a>Git Best Practices
|
||||
<ol>
|
||||
<li>All commit messages SHOULD follow the Commit Guidelines and format from
|
||||
<li id="clause-8-1"><a href="#clause-8-1" class="clause-link" aria-hidden="true"></a>All commit messages SHOULD follow the Commit Guidelines and format from
|
||||
the official git
|
||||
documentation:
|
||||
<a href="https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project">https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project</a></li>
|
||||
<li>You SHOULD never blindly commit all changes with "git commit -a". It is
|
||||
<li id="clause-8-2"><a href="#clause-8-2" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
<li>You SHOULD always use "--force-with-lease" when doing a force push. The
|
||||
<li id="clause-8-3"><a href="#clause-8-3" class="clause-link" aria-hidden="true"></a>You SHOULD always use "--force-with-lease" when doing a force push. The
|
||||
regular "--force" option is dangerous and destructive. More
|
||||
information:
|
||||
<a href="https://developer.atlassian.com/blog/2015/04/force-with-lease/">https://developer.atlassian.com/blog/2015/04/force-with-lease/</a></li>
|
||||
<li>You SHOULD understand and be comfortable with
|
||||
<li id="clause-8-4"><a href="#clause-8-4" class="clause-link" aria-hidden="true"></a>You SHOULD understand and be comfortable with
|
||||
rebasing: <a href="https://git-scm.com/book/en/v2/Git-Branching-Rebasing">https://git-scm.com/book/en/v2/Git-Branching-Rebasing</a></li>
|
||||
<li>It is RECOMMENDED that you always do "git pull --rebase" instead of "git
|
||||
<li id="clause-8-5"><a href="#clause-8-5" class="clause-link" aria-hidden="true"></a>It is RECOMMENDED that you always do "git pull --rebase" instead of "git
|
||||
pull" to avoid unnecessary merge commits. You can make this the default
|
||||
behavior of "git pull" with "git config --global pull.rebase true".</li>
|
||||
<li>It is RECOMMENDED that all branches be merged using "git merge --no-ff".
|
||||
<li id="clause-8-6"><a href="#clause-8-6" class="clause-link" aria-hidden="true"></a>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
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
document.documentElement.classList.add("dark");
|
||||
}
|
||||
})();
|
||||
</script><link rel="stylesheet" href="/_astro/index.Ds9Y8AeZ.css"></head> <body class="min-h-screen"> <header id="site-header" class="fixed top-0 inset-x-0 z-50 border-b border-transparent
|
||||
</script><link rel="stylesheet" href="/_astro/index.Dj4jDMY1.css"></head> <body class="min-h-screen"> <header id="site-header" class="fixed top-0 inset-x-0 z-50 border-b border-transparent
|
||||
translate-y-[-100%] transition-transform duration-300
|
||||
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"> <!-- Logo / Title + Version --> <div class="flex items-center gap-3"> <a href="#hero" class="flex items-center gap-3 no-underline
|
||||
text-gray-950 dark:text-neutral-50
|
||||
@@ -162,7 +162,7 @@ License
|
||||
lg:pr-8 lg:mr-8 lg:border-r border-gray-200 dark:border-neutral-800"> <nav class="space-y-1 py-2"> <div class="text-xs font-semibold uppercase tracking-wider mb-4
|
||||
text-gray-500 dark:text-neutral-500">
|
||||
Table of Contents
|
||||
</div> <a href="#terminology" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-sidebar-link data-section-id="terminology"> <span>Terminology</span> </a><a href="#specification" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-sidebar-link data-section-id="specification"> <span>Specification</span> </a><a href="#spec-tldr" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-tldr"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 1. </span> <span>TL;DR</span> </a><a href="#spec-the-master-branch" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-the-master-branch"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 2. </span> <span>The Master Branch</span> </a><a href="#spec-change-branches" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-change-branches"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 3. </span> <span>Change Branches</span> </a><a href="#spec-pull-requests" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-pull-requests"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 4. </span> <span>Pull Requests</span> </a><a href="#spec-versioning" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-versioning"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 5. </span> <span>Versioning</span> </a><a href="#spec-releases" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-releases"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 6. </span> <span>Releases</span> </a><a href="#spec-release-branches" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-release-branches"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 7. </span> <span>Release Branches</span> </a><a href="#spec-bug-fixes-rollback" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-bug-fixes-rollback"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 8. </span> <span>Bug Fixes & Rollback</span> </a><a href="#spec-git-best-practices" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="spec-git-best-practices"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 9. </span> <span>Git Best Practices</span> </a> </nav> </aside> <!-- Mobile floating button --> <button id="spec-toc-toggle" class="lg:hidden fixed bottom-6 right-6 z-40
|
||||
</div> <a href="#terminology" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-sidebar-link data-section-id="terminology"> <span>Terminology</span> </a><a href="#specification" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-sidebar-link data-section-id="specification"> <span>Specification</span> </a><a href="#clause-1" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-1"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 1. </span> <span>TL;DR</span> </a><a href="#clause-2" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-2"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 2. </span> <span>The Master Branch</span> </a><a href="#clause-3" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-3"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 3. </span> <span>Change Branches</span> </a><a href="#clause-4" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-4"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 4. </span> <span>Pull Requests</span> </a><a href="#clause-5" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-5"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 5. </span> <span>Versioning</span> </a><a href="#clause-6" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-6"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 6. </span> <span>Releases</span> </a><a href="#clause-7" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-7"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 7. </span> <span>Release Branches</span> </a><a href="#clause-8" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-8"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 8. </span> <span>Bug Fixes & Rollback</span> </a><a href="#clause-9" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-sidebar-link data-section-id="clause-9"> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 9. </span> <span>Git Best Practices</span> </a> </nav> </aside> <!-- Mobile floating button --> <button id="spec-toc-toggle" class="lg:hidden fixed bottom-6 right-6 z-40
|
||||
w-12 h-12 rounded-full shadow-lg
|
||||
bg-sky-600 text-white
|
||||
flex items-center justify-center
|
||||
@@ -172,7 +172,7 @@ Table of Contents
|
||||
rounded-t-2xl shadow-xl p-6"> <div class="flex items-center justify-between mb-4"> <span class="text-sm font-semibold uppercase tracking-wider
|
||||
text-gray-500 dark:text-neutral-500">
|
||||
Jump to Section
|
||||
</span> <button class="p-2 rounded-lg hover:bg-gray-100 dark:hover:bg-neutral-800" data-toc-close aria-label="Close"> <svg width="1em" height="1em" class="w-5 h-5" data-icon="heroicons:x-mark"> <symbol id="ai:heroicons:x-mark" viewBox="0 0 24 24"><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M6 18L18 6M6 6l12 12"/></symbol><use href="#ai:heroicons:x-mark"></use> </svg> </button> </div> <nav class="space-y-1"> <a href="#terminology" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-toc-link> <span>Terminology</span> </a><a href="#specification" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-toc-link> <span>Specification</span> </a><a href="#spec-tldr" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 1. </span> <span>TL;DR</span> </a><a href="#spec-the-master-branch" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 2. </span> <span>The Master Branch</span> </a><a href="#spec-change-branches" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 3. </span> <span>Change Branches</span> </a><a href="#spec-pull-requests" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 4. </span> <span>Pull Requests</span> </a><a href="#spec-versioning" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 5. </span> <span>Versioning</span> </a><a href="#spec-releases" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 6. </span> <span>Releases</span> </a><a href="#spec-release-branches" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 7. </span> <span>Release Branches</span> </a><a href="#spec-bug-fixes-rollback" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 8. </span> <span>Bug Fixes & Rollback</span> </a><a href="#spec-git-best-practices" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 9. </span> <span>Git Best Practices</span> </a> </nav> </div> </div> <script type="module" src="/_astro/SpecSidebar.astro_astro_type_script_index_0_lang.BQBj5HuJ.js"></script> </div> <!-- Main content --> <div class="flex-1 min-w-0"> <article class="prose-spec"> <!-- Terminology --> <section id="terminology"> <h2>Terminology</h2> <ul>
|
||||
</span> <button class="p-2 rounded-lg hover:bg-gray-100 dark:hover:bg-neutral-800" data-toc-close aria-label="Close"> <svg width="1em" height="1em" class="w-5 h-5" data-icon="heroicons:x-mark"> <symbol id="ai:heroicons:x-mark" viewBox="0 0 24 24"><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M6 18L18 6M6 6l12 12"/></symbol><use href="#ai:heroicons:x-mark"></use> </svg> </button> </div> <nav class="space-y-1"> <a href="#terminology" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-toc-link> <span>Terminology</span> </a><a href="#specification" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800" data-toc-link> <span>Specification</span> </a><a href="#clause-1" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 1. </span> <span>TL;DR</span> </a><a href="#clause-2" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 2. </span> <span>The Master Branch</span> </a><a href="#clause-3" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 3. </span> <span>Change Branches</span> </a><a href="#clause-4" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 4. </span> <span>Pull Requests</span> </a><a href="#clause-5" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 5. </span> <span>Versioning</span> </a><a href="#clause-6" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 6. </span> <span>Releases</span> </a><a href="#clause-7" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 7. </span> <span>Release Branches</span> </a><a href="#clause-8" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 8. </span> <span>Bug Fixes & Rollback</span> </a><a href="#clause-9" class="sidebar-link block py-2 px-4 text-sm rounded-md transition-colors text-gray-500 hover:text-gray-950 hover:bg-gray-100 dark:text-neutral-500 dark:hover:text-neutral-50 dark:hover:bg-neutral-800 pl-6 text-[0.8125rem] flex" data-toc-link> <span class="shrink-0 w-6 text-gray-400 dark:text-neutral-600"> 9. </span> <span>Git Best Practices</span> </a> </nav> </div> </div> <script type="module" src="/_astro/SpecSidebar.astro_astro_type_script_index_0_lang.BQBj5HuJ.js"></script> </div> <!-- Main content --> <div class="flex-1 min-w-0"> <article class="prose-spec"> <!-- Terminology --> <section id="terminology"> <h2>Terminology</h2> <ul>
|
||||
<li><strong>Master Branch</strong> - Must be named "master", must always have passing tests,
|
||||
and is not guaranteed to always work in production environments.</li>
|
||||
<li><strong>Change Branches</strong> - Any branch that introduces changes like a new feature, a
|
||||
@@ -194,142 +194,142 @@ also for long-term maintenance of older version.</li>
|
||||
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
|
||||
interpreted as described in <a href="https://tools.ietf.org/html/rfc2119">RFC 2119</a>.</p>
|
||||
<ol>
|
||||
<li id="spec-tldr">TL;DR
|
||||
<li id="clause-1"><a href="#clause-1" class="clause-link" aria-hidden="true"></a>TL;DR
|
||||
<ol>
|
||||
<li>Don't break the master branch.</li>
|
||||
<li>A release is a git tag.</li>
|
||||
<li id="clause-1-1"><a href="#clause-1-1" class="clause-link" aria-hidden="true"></a>Don't break the master branch.</li>
|
||||
<li id="clause-1-2"><a href="#clause-1-2" class="clause-link" aria-hidden="true"></a>A release is a git tag.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-the-master-branch">The Master Branch
|
||||
<li id="clause-2"><a href="#clause-2" class="clause-link" aria-hidden="true"></a>The Master Branch
|
||||
<ol>
|
||||
<li>A branch named "master" MUST exist and it MUST be referred to as the
|
||||
<li id="clause-2-1"><a href="#clause-2-1" class="clause-link" aria-hidden="true"></a>A branch named "master" MUST exist and it MUST be referred to as the
|
||||
"master branch".</li>
|
||||
<li>The master branch MUST always be in a non-broken state with its test
|
||||
<li id="clause-2-2"><a href="#clause-2-2" class="clause-link" aria-hidden="true"></a>The master branch MUST always be in a non-broken state with its test
|
||||
suite passing.</li>
|
||||
<li>The master branch IS NOT guaranteed to always work in production
|
||||
<li id="clause-2-3"><a href="#clause-2-3" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
<li>The master branch SHOULD always be in a "as near as possibly ready for
|
||||
<li id="clause-2-4"><a href="#clause-2-4" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-change-branches">Change Branches
|
||||
<li id="clause-3"><a href="#clause-3" class="clause-link" aria-hidden="true"></a>Change Branches
|
||||
<ol>
|
||||
<li>Each change (feature, bugfix, etc.) MUST be performed on separate
|
||||
<li id="clause-3-1"><a href="#clause-3-1" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
<li>You MUST create separate change branches for each distinctly different
|
||||
<li id="clause-3-2"><a href="#clause-3-2" class="clause-link" aria-hidden="true"></a>You MUST create separate change branches for each distinctly different
|
||||
change. You MUST NOT include multiple unrelated changes into a single
|
||||
change branch.</li>
|
||||
<li>When a change branch is created, the branch that it is created from
|
||||
<li id="clause-3-3"><a href="#clause-3-3" class="clause-link" aria-hidden="true"></a>When a change branch is created, the branch that it is created from
|
||||
SHOULD be referred to as the "source branch". Each change branch also
|
||||
needs a designated "merge target" branch, typically this will be the same
|
||||
as the source branch.</li>
|
||||
<li>Change branches MUST be regularly updated with any changes from their
|
||||
<li id="clause-3-4"><a href="#clause-3-4" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
<li>After rebasing a change branch on top of its source branch you MUST push
|
||||
<li id="clause-3-5"><a href="#clause-3-5" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-pull-requests">Pull Requests
|
||||
<li id="clause-4"><a href="#clause-4" class="clause-link" aria-hidden="true"></a>Pull Requests
|
||||
<ol>
|
||||
<li>To merge a change branch into its merge target, you MUST open a "pull
|
||||
<li id="clause-4-1"><a href="#clause-4-1" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
<li>A pull request MUST only be merged when the change branch is up-to-date
|
||||
<li id="clause-4-2"><a href="#clause-4-2" class="clause-link" aria-hidden="true"></a>A pull request MUST only be merged when the change branch is up-to-date
|
||||
with its source branch, the test suite is passing, and you and others are
|
||||
happy with the change. This is especially important if the merge target
|
||||
is the master branch.</li>
|
||||
<li>To get feedback, help, or generally just discuss a change branch with
|
||||
<li id="clause-4-3"><a href="#clause-4-3" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-versioning">Versioning
|
||||
<li id="clause-5"><a href="#clause-5" class="clause-link" aria-hidden="true"></a>Versioning
|
||||
<ol>
|
||||
<li>The project MUST have its version hard-coded somewhere in the
|
||||
<li id="clause-5-1"><a href="#clause-5-1" class="clause-link" aria-hidden="true"></a>The project MUST have its version hard-coded somewhere in the
|
||||
code-base. It is RECOMMENDED that this is done in a file called "VERSION"
|
||||
located in the root of the project.</li>
|
||||
<li>If you are using a "VERSION" file in the root of the project, this MUST
|
||||
<li id="clause-5-2"><a href="#clause-5-2" class="clause-link" aria-hidden="true"></a>If you are using a "VERSION" file in the root of the project, this MUST
|
||||
only contain the exact version string.</li>
|
||||
<li>The version string SHOULD follow the Semantic Versioning
|
||||
<li id="clause-5-3"><a href="#clause-5-3" class="clause-link" aria-hidden="true"></a>The version string SHOULD follow the Semantic Versioning
|
||||
(<a href="http://semver.org/">http://semver.org/</a>) format. Use of Semantic Versioning is OPTIONAL,
|
||||
but the version string MUST NOT have a "v" prefix. For example "v2.11.4"
|
||||
is bad, and "2.11.4" is good.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-releases">Releases
|
||||
<li id="clause-6"><a href="#clause-6" class="clause-link" aria-hidden="true"></a>Releases
|
||||
<ol>
|
||||
<li>To create a new release, you MUST create a "version bump" commit which
|
||||
<li id="clause-6-1"><a href="#clause-6-1" class="clause-link" aria-hidden="true"></a>To create a new release, you MUST create a "version bump" commit which
|
||||
changes the hard-coded version string of the project. The version bump
|
||||
commit MUST have a git tag created on it and named as the exact version
|
||||
string.</li>
|
||||
<li>If you are not using a release branch, then the version bump commit MUST
|
||||
<li id="clause-6-2"><a href="#clause-6-2" class="clause-link" aria-hidden="true"></a>If you are not using a release branch, then the version bump commit MUST
|
||||
be created directly on the master branch.</li>
|
||||
<li>The version bump commit MUST have a commit message title of "Bump version
|
||||
<li id="clause-6-3"><a href="#clause-6-3" class="clause-link" aria-hidden="true"></a>The version bump commit MUST have a commit message title of "Bump version
|
||||
to VERSION". For example, if the new version string is "2.11.4", the
|
||||
first line of the commit message MUST read: "Bump version to 2.11.4"</li>
|
||||
<li>The release tag on the version bump commit MUST be named exactly the same
|
||||
<li id="clause-6-4"><a href="#clause-6-4" class="clause-link" aria-hidden="true"></a>The release tag on the version bump commit MUST be named exactly the same
|
||||
as the version string. The tag name can OPTIONALLY be prefixed with
|
||||
"v". For example the tag name can be either "2.11.4" or "v2.11.4". You
|
||||
MUST not use a mix of "v" prefixed and non-prefixed tags. Pick one form
|
||||
and stick to it.</li>
|
||||
<li>It is RECOMMENDED that release tags are lightweight tags, but you can
|
||||
<li id="clause-6-5"><a href="#clause-6-5" class="clause-link" aria-hidden="true"></a>It is RECOMMENDED that release tags are lightweight tags, but you can
|
||||
OPTIONALLY use annotated tags if you want to include changelog
|
||||
information in the release tag itself.</li>
|
||||
<li>If you use annotated release tags, the first line of the annotation MUST
|
||||
<li id="clause-6-6"><a href="#clause-6-6" class="clause-link" aria-hidden="true"></a>If you use annotated release tags, the first line of the annotation MUST
|
||||
read "Release VERSION". For example for version "2.11.4" the first line
|
||||
of the tag annotation would read "Release 2.11.4". The second line must
|
||||
be blank, and the changelog MUST start on the third line.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-release-branches">Release Branches
|
||||
<li id="clause-7"><a href="#clause-7" class="clause-link" aria-hidden="true"></a>Release Branches
|
||||
<ol>
|
||||
<li>Any branch that has a name starting with "release-" SHOULD be referred to
|
||||
<li id="clause-7-1"><a href="#clause-7-1" class="clause-link" aria-hidden="true"></a>Any branch that has a name starting with "release-" SHOULD be referred to
|
||||
as a "release branch".</li>
|
||||
<li>Use of release branches is OPTIONAL.</li>
|
||||
<li>Changes in a release branch SHOULD typically come from work being
|
||||
<li id="clause-7-2"><a href="#clause-7-2" class="clause-link" aria-hidden="true"></a>Use of release branches is OPTIONAL.</li>
|
||||
<li id="clause-7-3"><a href="#clause-7-3" class="clause-link" aria-hidden="true"></a>Changes in a release branch SHOULD typically come from work being
|
||||
done against the master branch. Meaning changes SHOULD only trickle
|
||||
downwards from the master branch. If a change needs to trickle back up
|
||||
into the master branch, that work should have happened against the master
|
||||
branch in the first place. One exception to this is version bump commits.</li>
|
||||
<li>There are two types of release branches; short-term, and long-term.</li>
|
||||
<li>Short-Term Release Branches
|
||||
<li id="clause-7-4"><a href="#clause-7-4" class="clause-link" aria-hidden="true"></a>There are two types of release branches; short-term, and long-term.</li>
|
||||
<li id="clause-7-5"><a href="#clause-7-5" class="clause-link" aria-hidden="true"></a>Short-Term Release Branches
|
||||
<ol>
|
||||
<li>Used for creating a specific versioned release.</li>
|
||||
<li>A short-term release branch is RECOMMENDED if there is a lengthy
|
||||
<li id="clause-7-5-1"><a href="#clause-7-5-1" class="clause-link" aria-hidden="true"></a>Used for creating a specific versioned release.</li>
|
||||
<li id="clause-7-5-2"><a href="#clause-7-5-2" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
<li>MUST have a name of "release-VERSION". For example for version
|
||||
<li id="clause-7-5-3"><a href="#clause-7-5-3" class="clause-link" aria-hidden="true"></a>MUST have a name of "release-VERSION". For example for version
|
||||
"2.11.4" the release branch name MUST be "release-2.11.4".</li>
|
||||
<li>When using a short-term release branch, the version bump commit and
|
||||
<li id="clause-7-5-4"><a href="#clause-7-5-4" class="clause-link" aria-hidden="true"></a>When using a short-term release branch, the version bump commit and
|
||||
release tag MUST be made directly on the release branch itself.</li>
|
||||
<li>Only very minor changes should be performed on a short-term release
|
||||
<li id="clause-7-5-5"><a href="#clause-7-5-5" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
<li>After the version bump commit and release tag have been created, the
|
||||
<li id="clause-7-5-6"><a href="#clause-7-5-6" class="clause-link" aria-hidden="true"></a>After the version bump commit and release tag have been created, the
|
||||
release branch MUST be merged back into its source branch and then
|
||||
deleted. Typically the source branch will be the master branch.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Long-Term Release Branches
|
||||
<li id="clause-7-6"><a href="#clause-7-6" class="clause-link" aria-hidden="true"></a>Long-Term Release Branches
|
||||
<ol>
|
||||
<li>Used for work on versions which are not currently part of the master
|
||||
<li id="clause-7-6-1"><a href="#clause-7-6-1" class="clause-link" aria-hidden="true"></a>Used for work on versions which are not currently part of the master
|
||||
branch. Typically this is useful when you need to create a new
|
||||
maintenance release for a older version.</li>
|
||||
<li>The branch name MUST have a non-specific version number. For example
|
||||
<li id="clause-7-6-2"><a href="#clause-7-6-2" class="clause-link" aria-hidden="true"></a>The branch name MUST have a non-specific version number. For example
|
||||
a long-term release branch for creating new 2.9.x releases would be
|
||||
named "release-2.9".</li>
|
||||
<li>To create a new release from a long-term release branch, you MUST
|
||||
<li id="clause-7-6-3"><a href="#clause-7-6-3" class="clause-link" aria-hidden="true"></a>To create a new release from a long-term release branch, you MUST
|
||||
create a version bump commit and release tag directly on the release
|
||||
branch.</li>
|
||||
<li>A long-term release branch MUST be created from the relevant release
|
||||
<li id="clause-7-6-4"><a href="#clause-7-6-4" class="clause-link" aria-hidden="true"></a>A long-term release branch MUST be created from the relevant release
|
||||
tag. For example if the master branch is on version 2.11.4 and there
|
||||
is a security fix for all 2.9.x releases, the latest of which is
|
||||
"2.9.7". Create a new branch called "release-2.9" off of the "2.9.7"
|
||||
@@ -339,38 +339,38 @@ release tag. The security fix release will then end up being version
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-bug-fixes-rollback">Bug Fixes & Rollback
|
||||
<li id="clause-8"><a href="#clause-8" class="clause-link" aria-hidden="true"></a>Bug Fixes & Rollback
|
||||
<ol>
|
||||
<li>You MUST NOT under any circumstances force push to the master branch.</li>
|
||||
<li>If a change branch which has been merged into the master branch is found
|
||||
<li id="clause-8-1"><a href="#clause-8-1" class="clause-link" aria-hidden="true"></a>You MUST NOT under any circumstances force push to the master branch.</li>
|
||||
<li id="clause-8-2"><a href="#clause-8-2" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
<li>If a change branch is wrongfully merged into master, or for any other
|
||||
<li id="clause-8-3"><a href="#clause-8-3" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li id="spec-git-best-practices">Git Best Practices
|
||||
<li id="clause-9"><a href="#clause-9" class="clause-link" aria-hidden="true"></a>Git Best Practices
|
||||
<ol>
|
||||
<li>All commit messages SHOULD follow the Commit Guidelines and format from
|
||||
<li id="clause-9-1"><a href="#clause-9-1" class="clause-link" aria-hidden="true"></a>All commit messages SHOULD follow the Commit Guidelines and format from
|
||||
the official git
|
||||
documentation:
|
||||
<a href="https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines">https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines</a></li>
|
||||
<li>You SHOULD never blindly commit all changes with "git commit -a". It is
|
||||
<li id="clause-9-2"><a href="#clause-9-2" class="clause-link" aria-hidden="true"></a>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.</li>
|
||||
<li>You SHOULD always use "--force-with-lease" when doing a force push. The
|
||||
<li id="clause-9-3"><a href="#clause-9-3" class="clause-link" aria-hidden="true"></a>You SHOULD always use "--force-with-lease" when doing a force push. The
|
||||
regular "--force" option is dangerous and destructive. More
|
||||
information:
|
||||
<a href="https://developer.atlassian.com/blog/2015/04/force-with-lease/">https://developer.atlassian.com/blog/2015/04/force-with-lease/</a></li>
|
||||
<li>You SHOULD understand and be comfortable with
|
||||
<li id="clause-9-4"><a href="#clause-9-4" class="clause-link" aria-hidden="true"></a>You SHOULD understand and be comfortable with
|
||||
rebasing: <a href="https://git-scm.com/book/en/v2/Git-Branching-Rebasing">https://git-scm.com/book/en/v2/Git-Branching-Rebasing</a></li>
|
||||
<li>It is RECOMMENDED that you always do "git pull --rebase" instead of "git
|
||||
<li id="clause-9-5"><a href="#clause-9-5" class="clause-link" aria-hidden="true"></a>It is RECOMMENDED that you always do "git pull --rebase" instead of "git
|
||||
pull" to avoid unnecessary merge commits. You can make this the default
|
||||
behavior of "git pull" with "git config --global pull.rebase true".</li>
|
||||
<li>It is RECOMMENDED that all branches be merged using "git merge --no-ff".
|
||||
<li id="clause-9-6"><a href="#clause-9-6" class="clause-link" aria-hidden="true"></a>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
|
||||
|
||||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
Reference in New Issue
Block a user