mirror of
https://github.com/jimeh/commonflow.org.git
synced 2026-02-19 05:46:40 +00:00
Compare commits
11 Commits
1.0.0-rc.1
...
1.0.0-rc.2
| Author | SHA1 | Date | |
|---|---|---|---|
28c824ebb2
|
|||
|
f5b4d3c994
|
|||
|
6e96511e78
|
|||
|
8a51061b61
|
|||
|
054e3ec0f4
|
|||
|
aa3d03a4a4
|
|||
|
2e54b67e17
|
|||
|
38f557c49b
|
|||
|
dbd58eb80d
|
|||
|
02632bbf20
|
|||
|
1216fa2bc0
|
1
404.html
1
404.html
@@ -1,5 +1,6 @@
|
|||||||
---
|
---
|
||||||
title: 404 Page Not Found
|
title: 404 Page Not Found
|
||||||
|
sitemap: false
|
||||||
---
|
---
|
||||||
<div class="header">
|
<div class="header">
|
||||||
<h1>404</h1>
|
<h1>404</h1>
|
||||||
|
|||||||
1
Gemfile
1
Gemfile
@@ -21,6 +21,7 @@ end
|
|||||||
|
|
||||||
# If you have any plugins, put them here!
|
# If you have any plugins, put them here!
|
||||||
group :jekyll_plugins do
|
group :jekyll_plugins do
|
||||||
|
gem 'jekyll-pants'
|
||||||
gem 'jekyll-seo-tag'
|
gem 'jekyll-seo-tag'
|
||||||
gem 'jekyll-sitemap'
|
gem 'jekyll-sitemap'
|
||||||
end
|
end
|
||||||
|
|||||||
@@ -105,6 +105,8 @@ GEM
|
|||||||
jekyll-optional-front-matter (0.1.2)
|
jekyll-optional-front-matter (0.1.2)
|
||||||
jekyll (~> 3.0)
|
jekyll (~> 3.0)
|
||||||
jekyll-paginate (1.1.0)
|
jekyll-paginate (1.1.0)
|
||||||
|
jekyll-pants (0.2.1)
|
||||||
|
rubypants
|
||||||
jekyll-readme-index (0.1.0)
|
jekyll-readme-index (0.1.0)
|
||||||
jekyll (~> 3.0)
|
jekyll (~> 3.0)
|
||||||
jekyll-redirect-from (0.12.1)
|
jekyll-redirect-from (0.12.1)
|
||||||
@@ -188,6 +190,7 @@ GEM
|
|||||||
ruby-progressbar (~> 1.7)
|
ruby-progressbar (~> 1.7)
|
||||||
unicode-display_width (~> 1.0, >= 1.0.1)
|
unicode-display_width (~> 1.0, >= 1.0.1)
|
||||||
ruby-progressbar (1.8.1)
|
ruby-progressbar (1.8.1)
|
||||||
|
rubypants (0.6.0)
|
||||||
safe_yaml (1.0.4)
|
safe_yaml (1.0.4)
|
||||||
sass (3.4.24)
|
sass (3.4.24)
|
||||||
sawyer (0.8.1)
|
sawyer (0.8.1)
|
||||||
@@ -207,6 +210,7 @@ PLATFORMS
|
|||||||
|
|
||||||
DEPENDENCIES
|
DEPENDENCIES
|
||||||
github-pages
|
github-pages
|
||||||
|
jekyll-pants
|
||||||
jekyll-seo-tag
|
jekyll-seo-tag
|
||||||
jekyll-sitemap
|
jekyll-sitemap
|
||||||
rake
|
rake
|
||||||
|
|||||||
43
Rakefile
43
Rakefile
@@ -1,6 +1,11 @@
|
|||||||
require 'open-uri'
|
require 'open-uri'
|
||||||
require 'yaml'
|
require 'yaml'
|
||||||
|
|
||||||
|
desc 'Build site into docs directory'
|
||||||
|
task :build do
|
||||||
|
jekyll_build
|
||||||
|
end
|
||||||
|
|
||||||
desc 'Update index.md and spec folder based on versions in _config.yml'
|
desc 'Update index.md and spec folder based on versions in _config.yml'
|
||||||
task :update do
|
task :update do
|
||||||
config = YAML.load_file('_config.yml')
|
config = YAML.load_file('_config.yml')
|
||||||
@@ -22,6 +27,13 @@ task :update do
|
|||||||
write_file("#{filename}.md", spec[:body])
|
write_file("#{filename}.md", spec[:body])
|
||||||
write_file("#{filename}.svg", spec[:diagram]) if spec[:diagram]
|
write_file("#{filename}.svg", spec[:diagram]) if spec[:diagram]
|
||||||
end
|
end
|
||||||
|
|
||||||
|
jekyll_build
|
||||||
|
end
|
||||||
|
|
||||||
|
def jekyll_build
|
||||||
|
puts 'Rebuilding output into docs directory...'
|
||||||
|
exec 'jekyll build --destination docs && touch docs/.nojekyll'
|
||||||
end
|
end
|
||||||
|
|
||||||
def write_file(file, content, comment = nil)
|
def write_file(file, content, comment = nil)
|
||||||
@@ -30,15 +42,8 @@ def write_file(file, content, comment = nil)
|
|||||||
end
|
end
|
||||||
|
|
||||||
def fetch_spec(version, config)
|
def fetch_spec(version, config)
|
||||||
doc_url = config['url_tpl']
|
document = get(build_file_url('document', version, config))
|
||||||
.gsub('{{version}}', version)
|
diagram = get(build_file_url('diagram', version, config))
|
||||||
.gsub('{{file}}', config['files']['document'])
|
|
||||||
diagram_url = config['url_tpl']
|
|
||||||
.gsub('{{version}}', version)
|
|
||||||
.gsub('{{file}}', config['files']['diagram'])
|
|
||||||
|
|
||||||
document = get(doc_url)
|
|
||||||
diagram = get(diagram_url)
|
|
||||||
|
|
||||||
if diagram
|
if diagram
|
||||||
img_tag = config['img_tpl'].gsub('{{file}}', "#{version}.svg")
|
img_tag = config['img_tpl'].gsub('{{file}}', "#{version}.svg")
|
||||||
@@ -46,10 +51,9 @@ def fetch_spec(version, config)
|
|||||||
end
|
end
|
||||||
|
|
||||||
title = document.split("\n", 2).first
|
title = document.split("\n", 2).first
|
||||||
body = config['body_tpl']
|
body = config['body_tpl'].gsub('{{content}}', document)
|
||||||
.gsub('{{title}}', title)
|
.gsub('{{title}}', title)
|
||||||
.gsub('{{version}}', version)
|
.gsub('{{version}}', version)
|
||||||
.gsub('{{content}}', document)
|
|
||||||
|
|
||||||
{
|
{
|
||||||
version: version,
|
version: version,
|
||||||
@@ -59,15 +63,10 @@ def fetch_spec(version, config)
|
|||||||
}
|
}
|
||||||
end
|
end
|
||||||
|
|
||||||
def fetch_document(url)
|
def build_file_url(file, version, config)
|
||||||
response = get(url)
|
config['url_tpl']
|
||||||
{
|
.gsub('{{version}}', version)
|
||||||
|
.gsub('{{file}}', config['files'][file])
|
||||||
body: response
|
|
||||||
}
|
|
||||||
end
|
|
||||||
|
|
||||||
def fetch_diagram(url)
|
|
||||||
end
|
end
|
||||||
|
|
||||||
def get(url)
|
def get(url)
|
||||||
|
|||||||
12
_config.yml
12
_config.yml
@@ -5,10 +5,17 @@ description: >
|
|||||||
author: Jim Myhrberg
|
author: Jim Myhrberg
|
||||||
url: https://commonflow.org
|
url: https://commonflow.org
|
||||||
|
|
||||||
current_version: 1.0.0-rc.1
|
current_version: 1.0.0-rc.2
|
||||||
versions:
|
versions:
|
||||||
|
- 1.0.0-rc.2
|
||||||
- 1.0.0-rc.1
|
- 1.0.0-rc.1
|
||||||
|
|
||||||
|
exclude:
|
||||||
|
- Gemfile
|
||||||
|
- Gemfile.lock
|
||||||
|
- Rakefile
|
||||||
|
- README.md
|
||||||
|
|
||||||
update:
|
update:
|
||||||
body_tpl: |
|
body_tpl: |
|
||||||
---
|
---
|
||||||
@@ -24,6 +31,7 @@ update:
|
|||||||
diagram: common-flow.svg
|
diagram: common-flow.svg
|
||||||
|
|
||||||
gems:
|
gems:
|
||||||
|
- jekyll-pants
|
||||||
- jekyll-sitemap
|
- jekyll-sitemap
|
||||||
- jekyll-seo-tag
|
- jekyll-seo-tag
|
||||||
|
|
||||||
@@ -35,3 +43,5 @@ defaults:
|
|||||||
layout: "default"
|
layout: "default"
|
||||||
|
|
||||||
markdown: kramdown
|
markdown: kramdown
|
||||||
|
kramdown:
|
||||||
|
input: Pantsdown # disable smart quotes typographic symbols
|
||||||
|
|||||||
@@ -6,12 +6,7 @@
|
|||||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||||
<link href='https://fonts.googleapis.com/css?family=Open+Sans+Condensed:700,300|Open+Sans:400italic,700italic,400,700' rel='stylesheet' type='text/css'>
|
<link href='https://fonts.googleapis.com/css?family=Open+Sans+Condensed:700,300|Open+Sans:400italic,700italic,400,700' rel='stylesheet' type='text/css'>
|
||||||
<link rel="stylesheet" href="https://unpkg.com/purecss@1.0.0/build/pure-min.css" integrity="sha384-nn4HPE8lTHyVtfCBi5yW9d20FjT8BJwUXyWZT9InLYax14RDjBj46LmSztkmNP9w" crossorigin="anonymous">
|
<link rel="stylesheet" href="https://unpkg.com/purecss@1.0.0/build/pure-min.css" integrity="sha384-nn4HPE8lTHyVtfCBi5yW9d20FjT8BJwUXyWZT9InLYax14RDjBj46LmSztkmNP9w" crossorigin="anonymous">
|
||||||
<!--[if lte IE 8]>
|
|
||||||
<link rel="stylesheet" href="/css/main-old-ie.css">
|
|
||||||
<![endif]-->
|
|
||||||
<!--[if gt IE 8]><!-->
|
|
||||||
<link rel="stylesheet" href="/css/main.css">
|
<link rel="stylesheet" href="/css/main.css">
|
||||||
<!--<![endif]-->
|
|
||||||
{% seo %}
|
{% seo %}
|
||||||
</head>
|
</head>
|
||||||
<body>
|
<body>
|
||||||
|
|||||||
@@ -26,6 +26,10 @@ ol ol, ul ol {
|
|||||||
list-style-type: lower-roman;
|
list-style-type: lower-roman;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
ul ul ol, ul ol ol, ol ul ol, ol ol ol {
|
||||||
|
list-style-type: lower-alpha;
|
||||||
|
}
|
||||||
|
|
||||||
.content {
|
.content {
|
||||||
margin-top: 80px;
|
margin-top: 80px;
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,255 +0,0 @@
|
|||||||
body {
|
|
||||||
color: #777;
|
|
||||||
}
|
|
||||||
|
|
||||||
.pure-img-responsive {
|
|
||||||
max-width: 100%;
|
|
||||||
height: auto;
|
|
||||||
}
|
|
||||||
|
|
||||||
/*
|
|
||||||
Add transition to containers so they can push in and out.
|
|
||||||
*/
|
|
||||||
|
|
||||||
#layout,
|
|
||||||
#menu,
|
|
||||||
.menu-link {
|
|
||||||
-webkit-transition: all 0.2s ease-out;
|
|
||||||
-moz-transition: all 0.2s ease-out;
|
|
||||||
-ms-transition: all 0.2s ease-out;
|
|
||||||
-o-transition: all 0.2s ease-out;
|
|
||||||
transition: all 0.2s ease-out;
|
|
||||||
}
|
|
||||||
|
|
||||||
/*
|
|
||||||
This is the parent `<div>` that contains the menu and the content area.
|
|
||||||
*/
|
|
||||||
|
|
||||||
#layout {
|
|
||||||
position: relative;
|
|
||||||
left: 0;
|
|
||||||
padding-left: 0;
|
|
||||||
}
|
|
||||||
|
|
||||||
#layout.active #menu {
|
|
||||||
left: 150px;
|
|
||||||
width: 150px;
|
|
||||||
}
|
|
||||||
|
|
||||||
#layout.active .menu-link {
|
|
||||||
left: 150px;
|
|
||||||
}
|
|
||||||
|
|
||||||
/*
|
|
||||||
The content `<div>` is where all your content goes.
|
|
||||||
*/
|
|
||||||
|
|
||||||
.content {
|
|
||||||
margin: 0 auto;
|
|
||||||
padding: 0 2em;
|
|
||||||
max-width: 800px;
|
|
||||||
margin-bottom: 50px;
|
|
||||||
line-height: 1.6em;
|
|
||||||
}
|
|
||||||
|
|
||||||
.header {
|
|
||||||
margin: 0;
|
|
||||||
color: #333;
|
|
||||||
text-align: center;
|
|
||||||
padding: 2.5em 2em 0;
|
|
||||||
border-bottom: 1px solid #eee;
|
|
||||||
}
|
|
||||||
|
|
||||||
.header h1 {
|
|
||||||
margin: 0.2em 0;
|
|
||||||
font-size: 3em;
|
|
||||||
font-weight: 300;
|
|
||||||
}
|
|
||||||
|
|
||||||
.header h2 {
|
|
||||||
font-weight: 300;
|
|
||||||
color: #ccc;
|
|
||||||
padding: 0;
|
|
||||||
margin-top: 0;
|
|
||||||
}
|
|
||||||
|
|
||||||
.content-subhead {
|
|
||||||
margin: 50px 0 20px 0;
|
|
||||||
font-weight: 300;
|
|
||||||
color: #888;
|
|
||||||
}
|
|
||||||
|
|
||||||
/*
|
|
||||||
The `#menu` `<div>` is the parent `<div>` that contains the `.pure-menu` that
|
|
||||||
appears on the left side of the page.
|
|
||||||
*/
|
|
||||||
|
|
||||||
#menu {
|
|
||||||
margin-left: -150px;
|
|
||||||
/* "#menu" width */
|
|
||||||
width: 150px;
|
|
||||||
position: fixed;
|
|
||||||
top: 0;
|
|
||||||
left: 0;
|
|
||||||
bottom: 0;
|
|
||||||
z-index: 1000;
|
|
||||||
/* so the menu or its navicon stays above all content */
|
|
||||||
background: #191818;
|
|
||||||
overflow-y: auto;
|
|
||||||
-webkit-overflow-scrolling: touch;
|
|
||||||
}
|
|
||||||
|
|
||||||
/*
|
|
||||||
All anchors inside the menu should be styled like this.
|
|
||||||
*/
|
|
||||||
|
|
||||||
#menu a {
|
|
||||||
color: #999;
|
|
||||||
border: none;
|
|
||||||
padding: 0.6em 0 0.6em 0.6em;
|
|
||||||
}
|
|
||||||
|
|
||||||
/*
|
|
||||||
Remove all background/borders, since we are applying them to #menu.
|
|
||||||
*/
|
|
||||||
|
|
||||||
#menu .pure-menu,
|
|
||||||
#menu .pure-menu ul {
|
|
||||||
border: none;
|
|
||||||
background: transparent;
|
|
||||||
}
|
|
||||||
|
|
||||||
/*
|
|
||||||
Add that light border to separate items into groups.
|
|
||||||
*/
|
|
||||||
|
|
||||||
#menu .pure-menu ul,
|
|
||||||
#menu .pure-menu .menu-item-divided {
|
|
||||||
border-top: 1px solid #333;
|
|
||||||
}
|
|
||||||
|
|
||||||
/*
|
|
||||||
Change color of the anchor links on hover/focus.
|
|
||||||
*/
|
|
||||||
|
|
||||||
#menu .pure-menu li a:hover,
|
|
||||||
#menu .pure-menu li a:focus {
|
|
||||||
background: #333;
|
|
||||||
}
|
|
||||||
|
|
||||||
/*
|
|
||||||
This styles the selected menu item `<li>`.
|
|
||||||
*/
|
|
||||||
|
|
||||||
#menu .pure-menu-selected,
|
|
||||||
#menu .pure-menu-heading {
|
|
||||||
background: #1f8dd6;
|
|
||||||
}
|
|
||||||
|
|
||||||
/*
|
|
||||||
This styles a link within a selected menu item `<li>`.
|
|
||||||
*/
|
|
||||||
|
|
||||||
#menu .pure-menu-selected a {
|
|
||||||
color: #fff;
|
|
||||||
}
|
|
||||||
|
|
||||||
/*
|
|
||||||
This styles the menu heading.
|
|
||||||
*/
|
|
||||||
|
|
||||||
#menu .pure-menu-heading {
|
|
||||||
font-size: 110%;
|
|
||||||
color: #fff;
|
|
||||||
margin: 0;
|
|
||||||
}
|
|
||||||
|
|
||||||
/* -- Dynamic Button For Responsive Menu -------------------------------------*/
|
|
||||||
|
|
||||||
/*
|
|
||||||
The button to open/close the Menu is custom-made and not part of Pure. Here's
|
|
||||||
how it works:
|
|
||||||
*/
|
|
||||||
|
|
||||||
/*
|
|
||||||
`.menu-link` represents the responsive menu toggle that shows/hides on
|
|
||||||
small screens.
|
|
||||||
*/
|
|
||||||
|
|
||||||
.menu-link {
|
|
||||||
position: fixed;
|
|
||||||
display: block;
|
|
||||||
/* show this only on small screens */
|
|
||||||
top: 0;
|
|
||||||
left: 0;
|
|
||||||
/* "#menu width" */
|
|
||||||
background: #000;
|
|
||||||
background: rgba(0,0,0,0.7);
|
|
||||||
font-size: 10px;
|
|
||||||
/* change this value to increase/decrease button size */
|
|
||||||
z-index: 10;
|
|
||||||
width: 2em;
|
|
||||||
height: auto;
|
|
||||||
padding: 2.1em 1.6em;
|
|
||||||
}
|
|
||||||
|
|
||||||
.menu-link:hover,
|
|
||||||
.menu-link:focus {
|
|
||||||
background: #000;
|
|
||||||
}
|
|
||||||
|
|
||||||
.menu-link span {
|
|
||||||
position: relative;
|
|
||||||
display: block;
|
|
||||||
}
|
|
||||||
|
|
||||||
.menu-link span,
|
|
||||||
.menu-link span:before,
|
|
||||||
.menu-link span:after {
|
|
||||||
background-color: #fff;
|
|
||||||
width: 100%;
|
|
||||||
height: 0.2em;
|
|
||||||
}
|
|
||||||
|
|
||||||
.menu-link span:before,
|
|
||||||
.menu-link span:after {
|
|
||||||
position: absolute;
|
|
||||||
margin-top: -0.6em;
|
|
||||||
content: " ";
|
|
||||||
}
|
|
||||||
|
|
||||||
.menu-link span:after {
|
|
||||||
margin-top: 0.6em;
|
|
||||||
}
|
|
||||||
|
|
||||||
/* -- Responsive Styles (Media Queries) ------------------------------------- */
|
|
||||||
|
|
||||||
/*
|
|
||||||
Hides the menu at `48em`, but modify this based on your app's needs.
|
|
||||||
*/
|
|
||||||
|
|
||||||
.header,
|
|
||||||
.content {
|
|
||||||
padding-left: 2em;
|
|
||||||
padding-right: 2em;
|
|
||||||
}
|
|
||||||
|
|
||||||
#layout {
|
|
||||||
padding-left: 150px;
|
|
||||||
/* left col width "#menu" */
|
|
||||||
left: 0;
|
|
||||||
}
|
|
||||||
|
|
||||||
#menu {
|
|
||||||
left: 150px;
|
|
||||||
}
|
|
||||||
|
|
||||||
.menu-link {
|
|
||||||
position: fixed;
|
|
||||||
left: 150px;
|
|
||||||
display: none;
|
|
||||||
}
|
|
||||||
|
|
||||||
#layout.active .menu-link {
|
|
||||||
left: 150px;
|
|
||||||
}
|
|
||||||
@@ -1,9 +0,0 @@
|
|||||||
---
|
|
||||||
layout: none
|
|
||||||
---
|
|
||||||
|
|
||||||
// Import partials from `sass_dir` (defaults to `_sass`)
|
|
||||||
@import
|
|
||||||
"side-menu-old-ie",
|
|
||||||
"base"
|
|
||||||
;
|
|
||||||
0
docs/.nojekyll
Normal file
0
docs/.nojekyll
Normal file
74
docs/404.html
Normal file
74
docs/404.html
Normal file
@@ -0,0 +1,74 @@
|
|||||||
|
<!DOCTYPE html>
|
||||||
|
<html>
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8">
|
||||||
|
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||||
|
<link href='https://fonts.googleapis.com/css?family=Open+Sans+Condensed:700,300|Open+Sans:400italic,700italic,400,700' rel='stylesheet' type='text/css'>
|
||||||
|
<link rel="stylesheet" href="https://unpkg.com/purecss@1.0.0/build/pure-min.css" integrity="sha384-nn4HPE8lTHyVtfCBi5yW9d20FjT8BJwUXyWZT9InLYax14RDjBj46LmSztkmNP9w" crossorigin="anonymous">
|
||||||
|
<link rel="stylesheet" href="/css/main.css">
|
||||||
|
<!-- Begin Jekyll SEO tag v2.2.3 -->
|
||||||
|
<title>404 Page Not Found | Git Common Flow</title>
|
||||||
|
<meta property="og:title" content="404 Page Not Found" />
|
||||||
|
<meta name="author" content="Jim Myhrberg" />
|
||||||
|
<meta property="og:locale" content="en_US" />
|
||||||
|
<meta name="description" content="An attempt to gather a sensible selection of the most common usage patterns of git into a single and concise specification." />
|
||||||
|
<meta property="og:description" content="An attempt to gather a sensible selection of the most common usage patterns of git into a single and concise specification." />
|
||||||
|
<link rel="canonical" href="https://commonflow.org/404.html" />
|
||||||
|
<meta property="og:url" content="https://commonflow.org/404.html" />
|
||||||
|
<meta property="og:site_name" content="Git Common Flow" />
|
||||||
|
<script type="application/ld+json">
|
||||||
|
{"@context":"http://schema.org","@type":"WebPage","headline":"404 Page Not Found","author":{"@type":"Person","name":"Jim Myhrberg"},"description":"An attempt to gather a sensible selection of the most common usage patterns of git into a single and concise specification.","url":"https://commonflow.org/404.html"}</script>
|
||||||
|
<!-- End Jekyll SEO tag -->
|
||||||
|
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<div id="layout">
|
||||||
|
<a href="#menu" id="menuLink" class="menu-link">
|
||||||
|
<span></span>
|
||||||
|
</a>
|
||||||
|
<div id="menu">
|
||||||
|
<div class="pure-menu">
|
||||||
|
<ul class="pure-menu-list">
|
||||||
|
<li class="pure-menu-item">
|
||||||
|
<div class="pure-menu-label">Versions:</div>
|
||||||
|
</li>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
<li class="pure-menu-item version-1.0.0-rc.2">
|
||||||
|
<a href="/spec/1.0.0-rc.2.html" class="pure-menu-link">1.0.0-rc.2</a>
|
||||||
|
</li>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
<li class="pure-menu-item version-1.0.0-rc.1">
|
||||||
|
<a href="/spec/1.0.0-rc.1.html" class="pure-menu-link">1.0.0-rc.1</a>
|
||||||
|
</li>
|
||||||
|
|
||||||
|
|
||||||
|
</ul>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div id="main">
|
||||||
|
<div class="content">
|
||||||
|
<div class="header">
|
||||||
|
<h1>404</h1>
|
||||||
|
<p><strong>Page not found :(</strong></p>
|
||||||
|
<p>The requested page could not be found.</p>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<script src="/js/ui.js"></script>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
1
docs/CNAME
Normal file
1
docs/CNAME
Normal file
@@ -0,0 +1 @@
|
|||||||
|
commonflow.org
|
||||||
123
docs/css/main.css
Normal file
123
docs/css/main.css
Normal file
@@ -0,0 +1,123 @@
|
|||||||
|
body { color: #777; }
|
||||||
|
|
||||||
|
.pure-img-responsive { max-width: 100%; height: auto; }
|
||||||
|
|
||||||
|
/*
|
||||||
|
Add transition to containers so they can push in and out.
|
||||||
|
*/
|
||||||
|
#layout, #menu, .menu-link { -webkit-transition: all 0.2s ease-out; -moz-transition: all 0.2s ease-out; -ms-transition: all 0.2s ease-out; -o-transition: all 0.2s ease-out; transition: all 0.2s ease-out; }
|
||||||
|
|
||||||
|
/*
|
||||||
|
This is the parent `<div>` that contains the menu and the content area.
|
||||||
|
*/
|
||||||
|
#layout { position: relative; left: 0; padding-left: 0; }
|
||||||
|
|
||||||
|
#layout.active #menu { left: 150px; width: 150px; }
|
||||||
|
|
||||||
|
#layout.active .menu-link { left: 150px; }
|
||||||
|
|
||||||
|
/*
|
||||||
|
The content `<div>` is where all your content goes.
|
||||||
|
*/
|
||||||
|
.content { margin: 0 auto; padding: 0 2em; max-width: 800px; margin-bottom: 50px; line-height: 1.6em; }
|
||||||
|
|
||||||
|
.header { margin: 0; color: #333; text-align: center; padding: 2.5em 2em 0; border-bottom: 1px solid #eee; }
|
||||||
|
|
||||||
|
.header h1 { margin: 0.2em 0; font-size: 3em; font-weight: 300; }
|
||||||
|
|
||||||
|
.header h2 { font-weight: 300; color: #ccc; padding: 0; margin-top: 0; }
|
||||||
|
|
||||||
|
.content-subhead { margin: 50px 0 20px 0; font-weight: 300; color: #888; }
|
||||||
|
|
||||||
|
/*
|
||||||
|
The `#menu` `<div>` is the parent `<div>` that contains the `.pure-menu` that
|
||||||
|
appears on the left side of the page.
|
||||||
|
*/
|
||||||
|
#menu { margin-left: -150px; /* "#menu" width */ width: 150px; position: fixed; top: 0; left: 0; bottom: 0; z-index: 1000; /* so the menu or its navicon stays above all content */ background: #191818; overflow-y: auto; -webkit-overflow-scrolling: touch; }
|
||||||
|
|
||||||
|
/*
|
||||||
|
All anchors inside the menu should be styled like this.
|
||||||
|
*/
|
||||||
|
#menu a { color: #999; border: none; padding: 0.6em 0 0.6em 0.6em; }
|
||||||
|
|
||||||
|
/*
|
||||||
|
Remove all background/borders, since we are applying them to #menu.
|
||||||
|
*/
|
||||||
|
#menu .pure-menu, #menu .pure-menu ul { border: none; background: transparent; }
|
||||||
|
|
||||||
|
/*
|
||||||
|
Add that light border to separate items into groups.
|
||||||
|
*/
|
||||||
|
#menu .pure-menu ul, #menu .pure-menu .menu-item-divided { border-top: 1px solid #333; }
|
||||||
|
|
||||||
|
/*
|
||||||
|
Change color of the anchor links on hover/focus.
|
||||||
|
*/
|
||||||
|
#menu .pure-menu li a:hover, #menu .pure-menu li a:focus { background: #333; }
|
||||||
|
|
||||||
|
/*
|
||||||
|
This styles the selected menu item `<li>`.
|
||||||
|
*/
|
||||||
|
#menu .pure-menu-selected, #menu .pure-menu-heading { background: #1f8dd6; }
|
||||||
|
|
||||||
|
/*
|
||||||
|
This styles a link within a selected menu item `<li>`.
|
||||||
|
*/
|
||||||
|
#menu .pure-menu-selected a { color: #fff; }
|
||||||
|
|
||||||
|
/*
|
||||||
|
This styles the menu heading.
|
||||||
|
*/
|
||||||
|
#menu .pure-menu-heading { font-size: 110%; color: #fff; margin: 0; }
|
||||||
|
|
||||||
|
/* -- Dynamic Button For Responsive Menu -------------------------------------*/
|
||||||
|
/*
|
||||||
|
The button to open/close the Menu is custom-made and not part of Pure. Here's
|
||||||
|
how it works:
|
||||||
|
*/
|
||||||
|
/*
|
||||||
|
`.menu-link` represents the responsive menu toggle that shows/hides on
|
||||||
|
small screens.
|
||||||
|
*/
|
||||||
|
.menu-link { position: fixed; display: block; /* show this only on small screens */ top: 0; left: 0; /* "#menu width" */ background: #000; background: rgba(0, 0, 0, 0.7); font-size: 10px; /* change this value to increase/decrease button size */ z-index: 10; width: 2em; height: auto; padding: 2.1em 1.6em; }
|
||||||
|
|
||||||
|
.menu-link:hover, .menu-link:focus { background: #000; }
|
||||||
|
|
||||||
|
.menu-link span { position: relative; display: block; }
|
||||||
|
|
||||||
|
.menu-link span, .menu-link span:before, .menu-link span:after { background-color: #fff; width: 100%; height: 0.2em; }
|
||||||
|
|
||||||
|
.menu-link span:before, .menu-link span:after { position: absolute; margin-top: -0.6em; content: " "; }
|
||||||
|
|
||||||
|
.menu-link span:after { margin-top: 0.6em; }
|
||||||
|
|
||||||
|
/* -- Responsive Styles (Media Queries) ------------------------------------- */
|
||||||
|
/*
|
||||||
|
Hides the menu at `48em`, but modify this based on your app's needs.
|
||||||
|
*/
|
||||||
|
@media (min-width: 48em) { .header, .content { padding-left: 2em; padding-right: 2em; }
|
||||||
|
#layout { padding-left: 150px; /* left col width "#menu" */ left: 0; }
|
||||||
|
#menu { left: 150px; }
|
||||||
|
.menu-link { position: fixed; left: 150px; display: none; }
|
||||||
|
#layout.active .menu-link { left: 150px; } }
|
||||||
|
@media (max-width: 48em) { /* Only apply this when the window is small. Otherwise, the following case results in extra padding on the left: Make the window small. Tap the menu to trigger the active state. Make the window large again. */
|
||||||
|
#layout.active { position: relative; left: 150px; } }
|
||||||
|
html { height: 100%; }
|
||||||
|
|
||||||
|
body { font-family: 'Open Sans', Helvetica, Arial, sans-serif; font-size: 16px; font-weight: 400; line-height: 1.5; color: #1a1a1a; background-color: #fdfdfd; }
|
||||||
|
|
||||||
|
h1, h2, h3, h4, h5, h6 { font-family: 'Open Sans Condensed', Helvetica, Arial, sans-serif; font-weight: 700; color: #333; }
|
||||||
|
|
||||||
|
h1 { font-size: 2.5em; line-height: 1.2; }
|
||||||
|
|
||||||
|
ol ol, ul ol { list-style-type: lower-roman; }
|
||||||
|
|
||||||
|
ul ul ol, ul ol ol, ol ul ol, ol ol ol { list-style-type: lower-alpha; }
|
||||||
|
|
||||||
|
.content { margin-top: 80px; }
|
||||||
|
|
||||||
|
.content a { word-break: break-word; }
|
||||||
|
|
||||||
|
.content code { background-color: rgba(27, 31, 35, 0.05); border-radius: 3px; font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, Courier, monospace; font-size: 90%; margin: 0; padding: 0.2em; }
|
||||||
|
|
||||||
|
#menu .pure-menu-label { color: #999; border: none; padding: 0.6em 0 0.6em 0.6em; }
|
||||||
302
docs/index.html
Normal file
302
docs/index.html
Normal file
@@ -0,0 +1,302 @@
|
|||||||
|
<!DOCTYPE html>
|
||||||
|
<html>
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8">
|
||||||
|
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||||
|
<link href='https://fonts.googleapis.com/css?family=Open+Sans+Condensed:700,300|Open+Sans:400italic,700italic,400,700' rel='stylesheet' type='text/css'>
|
||||||
|
<link rel="stylesheet" href="https://unpkg.com/purecss@1.0.0/build/pure-min.css" integrity="sha384-nn4HPE8lTHyVtfCBi5yW9d20FjT8BJwUXyWZT9InLYax14RDjBj46LmSztkmNP9w" crossorigin="anonymous">
|
||||||
|
<link rel="stylesheet" href="/css/main.css">
|
||||||
|
<!-- Begin Jekyll SEO tag v2.2.3 -->
|
||||||
|
<title>Git Common-Flow 1.0.0-rc.2 | Git Common Flow</title>
|
||||||
|
<meta property="og:title" content="Git Common-Flow 1.0.0-rc.2" />
|
||||||
|
<meta name="author" content="Jim Myhrberg" />
|
||||||
|
<meta property="og:locale" content="en_US" />
|
||||||
|
<meta name="description" content="An attempt to gather a sensible selection of the most common usage patterns of git into a single and concise specification." />
|
||||||
|
<meta property="og:description" content="An attempt to gather a sensible selection of the most common usage patterns of git into a single and concise specification." />
|
||||||
|
<link rel="canonical" href="https://commonflow.org/" />
|
||||||
|
<meta property="og:url" content="https://commonflow.org/" />
|
||||||
|
<meta property="og:site_name" content="Git Common Flow" />
|
||||||
|
<script type="application/ld+json">
|
||||||
|
{"@context":"http://schema.org","@type":"WebSite","name":"Git Common Flow","headline":"Git Common-Flow 1.0.0-rc.2","author":{"@type":"Person","name":"Jim Myhrberg"},"description":"An attempt to gather a sensible selection of the most common usage patterns of git into a single and concise specification.","url":"https://commonflow.org/"}</script>
|
||||||
|
<!-- End Jekyll SEO tag -->
|
||||||
|
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<div id="layout">
|
||||||
|
<a href="#menu" id="menuLink" class="menu-link">
|
||||||
|
<span></span>
|
||||||
|
</a>
|
||||||
|
<div id="menu">
|
||||||
|
<div class="pure-menu">
|
||||||
|
<ul class="pure-menu-list">
|
||||||
|
<li class="pure-menu-item">
|
||||||
|
<div class="pure-menu-label">Versions:</div>
|
||||||
|
</li>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
<li class="pure-menu-item version-1.0.0-rc.2 pure-menu-selected">
|
||||||
|
<a href="/spec/1.0.0-rc.2.html" class="pure-menu-link">1.0.0-rc.2</a>
|
||||||
|
</li>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
<li class="pure-menu-item version-1.0.0-rc.1">
|
||||||
|
<a href="/spec/1.0.0-rc.1.html" class="pure-menu-link">1.0.0-rc.1</a>
|
||||||
|
</li>
|
||||||
|
|
||||||
|
|
||||||
|
</ul>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div id="main">
|
||||||
|
<div class="content">
|
||||||
|
<h1 id="git-common-flow-100-rc2">Git Common-Flow 1.0.0-rc.2</h1>
|
||||||
|
|
||||||
|
<p><img src="/spec/1.0.0-rc.2.svg" width="100%" /></p>
|
||||||
|
|
||||||
|
<h2 id="summary">Summary</h2>
|
||||||
|
|
||||||
|
<p>Common-Flow is an attempt to gather a sensible selection of the most common
|
||||||
|
usage patterns of git into a single and concise specification. It is based on
|
||||||
|
the <a href="http://scottchacon.com/2011/08/31/github-flow.html">original variant</a>
|
||||||
|
of <a href="https://guides.github.com/introduction/flow/">GitHub Flow</a>, while taking
|
||||||
|
into account how a lot of open source projects use git.</p>
|
||||||
|
|
||||||
|
<p>TL;DR: Common-Flow is basically GitHub Flow with the addition of versioned
|
||||||
|
releases, maintenance releases for old versions, and without the requirement to
|
||||||
|
deploy to production all the time.</p>
|
||||||
|
|
||||||
|
<h2 id="terminology">Terminology</h2>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>Master Branch</strong> - Must always have passing tests, is considered bleeding
|
||||||
|
edge, and must be named <code class="highlighter-rouge">master</code>.</li>
|
||||||
|
<li><strong>Change Branches</strong> - Any branch that introduces changes like a new feature, a
|
||||||
|
bug fix, etc.</li>
|
||||||
|
<li><strong>Source Branch</strong> - The branch that a change branch was created from. New
|
||||||
|
changes in the source branch should be incorporated into the change branch via
|
||||||
|
rebasing.</li>
|
||||||
|
<li><strong>Merge Target</strong> - A branch that is the intended merge target for a change
|
||||||
|
branch. Typically the merge target branch will be the same as the source
|
||||||
|
branch.</li>
|
||||||
|
<li><strong>Pull Request</strong> - A means of requesting that a change branch is merged in to
|
||||||
|
its merge target, allowing others to review, discuss and approve the changes.</li>
|
||||||
|
<li><strong>Release</strong> - Consists of a version bump commit, and a git tag named according
|
||||||
|
to the new version string placed on said commit.</li>
|
||||||
|
<li><strong>Release Branches</strong> - Used both for short-term preparations of a release, and
|
||||||
|
also for long-term maintenance of older version.</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h2 id="git-common-flow-specification-common-flow">Git Common-Flow Specification (Common-Flow)</h2>
|
||||||
|
|
||||||
|
<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
|
||||||
|
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
|
||||||
|
interpreted as described in <a href="https://tools.ietf.org/html/rfc2119">RFC 2119</a>.</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>The Master Branch
|
||||||
|
<ol>
|
||||||
|
<li>A branch named "master" MUST exist and it MUST be referred to as the
|
||||||
|
"master branch".</li>
|
||||||
|
<li>The master branch MUST be considered bleeding edge.</li>
|
||||||
|
<li>The master branch MUST always be in a non-broken state with its test
|
||||||
|
suite passing.</li>
|
||||||
|
<li>The master branch SHOULD always be in a "as near as possibly ready for
|
||||||
|
release/production" state to reduce any friction with creating a new
|
||||||
|
release.</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
<li>Change Branches
|
||||||
|
<ol>
|
||||||
|
<li>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
|
||||||
|
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
|
||||||
|
SHOULD be referred to as the "source branch". Each change branch also
|
||||||
|
needs a designated "merge target" branch, typically this will be the same
|
||||||
|
as the source branch.</li>
|
||||||
|
<li>Change branches MUST be regularly updated with any changes from their
|
||||||
|
source branch. This MUST be done by rebasing the change branch on top of
|
||||||
|
the source branch.</li>
|
||||||
|
<li>After rebasing a change branch on top of its source branch you MUST push
|
||||||
|
the change branch to the remote server. This will require you to do a
|
||||||
|
force push, and you SHOULD use the "--force-with-lease" git push option.</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
<li>Pull Requests
|
||||||
|
<ol>
|
||||||
|
<li>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
|
||||||
|
with its source branch, the test suite is passing, and you and others are
|
||||||
|
happy with the change. This is especially important if the merge target
|
||||||
|
is the master branch.</li>
|
||||||
|
<li>To get feedback, help, or generally just discuss a change branch with
|
||||||
|
others, the RECOMMENDED way to do so is by creating a pull request and
|
||||||
|
discuss the changes with others there.</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
<li>Versioning
|
||||||
|
<ol>
|
||||||
|
<li>The project MUST have its version hard-coded somewhere in the
|
||||||
|
code-base. It is RECOMMENDED that this is done in a file called "VERSION"
|
||||||
|
located in the root of the project.</li>
|
||||||
|
<li>If you are using a "VERSION" file in the root of the project, this MUST
|
||||||
|
only contain the exact version string.</li>
|
||||||
|
<li>The version string SHOULD follow the Semantic Versioning
|
||||||
|
(<a href="http://semver.org/">http://semver.org/</a>) format. Use of Semantic Versioning is OPTIONAL,
|
||||||
|
but the version string MUST NOT have a "v" prefix. For example "v2.11.4"
|
||||||
|
is bad, and "2.11.4" is good.</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
<li>Releases
|
||||||
|
<ol>
|
||||||
|
<li>To create a new release, you MUST create a "version bump" commit 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
|
||||||
|
be created directly on the master branch.</li>
|
||||||
|
<li>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
|
||||||
|
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
|
||||||
|
OPTIONALLY use annotated tags if you want to include changelog
|
||||||
|
information in the release tag itself.</li>
|
||||||
|
<li>If you use annotated release tags, the first line of the annotation MUST
|
||||||
|
read "Release VERSION". For example for version "2.11.4" the first line
|
||||||
|
of the tag annotation would read "Release 2.11.4". The second line must
|
||||||
|
be blank, and the changelog MUST start on the third line.</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
<li>Release Branches
|
||||||
|
<ol>
|
||||||
|
<li>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
|
||||||
|
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
|
||||||
|
<ol>
|
||||||
|
<li>Used for creating a specific versioned release.</li>
|
||||||
|
<li>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
|
||||||
|
"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
|
||||||
|
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
|
||||||
|
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
|
||||||
|
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
|
||||||
|
<ol>
|
||||||
|
<li>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
|
||||||
|
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
|
||||||
|
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
|
||||||
|
tag. For example if the master branch is on version 2.11.4 and there
|
||||||
|
is a security fix for all 2.9.x releases, the latest of which is
|
||||||
|
"2.9.7". Create a new branch called "release-2.9" off of the "2.9.7"
|
||||||
|
release tag. The security fix release will then end up being version
|
||||||
|
"2.9.8".</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
<li>Bug Fixes & Rollback
|
||||||
|
<ol>
|
||||||
|
<li>You MUST NOT under any circumstances force push to the master branch.</li>
|
||||||
|
<li>If a change branch which has been merged 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
|
||||||
|
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>Git Best Practices
|
||||||
|
<ol>
|
||||||
|
<li>All commit messages SHOULD follow the Commit Guidelines and format from
|
||||||
|
the official git
|
||||||
|
documentation:
|
||||||
|
<a href="https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project">https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project</a></li>
|
||||||
|
<li>You SHOULD 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
|
||||||
|
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
|
||||||
|
rebasing: <a href="https://git-scm.com/book/en/v2/Git-Branching-Rebasing">https://git-scm.com/book/en/v2/Git-Branching-Rebasing</a></li>
|
||||||
|
<li>It is RECOMMENDED that you always do "git pull --rebase" instead of "git
|
||||||
|
pull" to avoid unnecessary merge commits. You can make this the default
|
||||||
|
behavior of "git pull" with "git config --global pull.rebase true".</li>
|
||||||
|
<li>It is RECOMMENDED that all branches be merged using "git merge --no-ff".
|
||||||
|
This makes sure the reference to the original branch is kept in the
|
||||||
|
commits, allows one to revert a merge by reverting a single merge commit,
|
||||||
|
and creates a merge commit to mark the integration of the branch with
|
||||||
|
master.</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h2 id="about">About</h2>
|
||||||
|
|
||||||
|
<p>The Git Common-Flow specification is authored
|
||||||
|
by <a href="http://jimeh.me">Jim Myhrberg</a>.</p>
|
||||||
|
|
||||||
|
<p>If you'd like to leave feedback,
|
||||||
|
please <a href="https://github.com/jimeh/common-flow/issues">open an issue on GitHub</a>.</p>
|
||||||
|
|
||||||
|
<h2 id="license">License</h2>
|
||||||
|
|
||||||
|
<p><a href="http://creativecommons.org/licenses/by/3.0/">Creative Commons - CC BY 3.0</a></p>
|
||||||
|
|
||||||
|
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<script src="/js/ui.js"></script>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
46
docs/js/ui.js
Normal file
46
docs/js/ui.js
Normal file
@@ -0,0 +1,46 @@
|
|||||||
|
(function (window, document) {
|
||||||
|
|
||||||
|
var layout = document.getElementById('layout'),
|
||||||
|
menu = document.getElementById('menu'),
|
||||||
|
menuLink = document.getElementById('menuLink'),
|
||||||
|
content = document.getElementById('main');
|
||||||
|
|
||||||
|
function toggleClass(element, className) {
|
||||||
|
var classes = element.className.split(/\s+/),
|
||||||
|
length = classes.length,
|
||||||
|
i = 0;
|
||||||
|
|
||||||
|
for(; i < length; i++) {
|
||||||
|
if (classes[i] === className) {
|
||||||
|
classes.splice(i, 1);
|
||||||
|
break;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
// The className is not found
|
||||||
|
if (length === classes.length) {
|
||||||
|
classes.push(className);
|
||||||
|
}
|
||||||
|
|
||||||
|
element.className = classes.join(' ');
|
||||||
|
}
|
||||||
|
|
||||||
|
function toggleAll(e) {
|
||||||
|
var active = 'active';
|
||||||
|
|
||||||
|
e.preventDefault();
|
||||||
|
toggleClass(layout, active);
|
||||||
|
toggleClass(menu, active);
|
||||||
|
toggleClass(menuLink, active);
|
||||||
|
}
|
||||||
|
|
||||||
|
menuLink.onclick = function (e) {
|
||||||
|
toggleAll(e);
|
||||||
|
};
|
||||||
|
|
||||||
|
content.onclick = function(e) {
|
||||||
|
if (menu.className.indexOf('active') !== -1) {
|
||||||
|
toggleAll(e);
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
}(this, this.document));
|
||||||
1
docs/robots.txt
Normal file
1
docs/robots.txt
Normal file
@@ -0,0 +1 @@
|
|||||||
|
Sitemap: https://commonflow.org/sitemap.xml
|
||||||
12
docs/sitemap.xml
Normal file
12
docs/sitemap.xml
Normal file
@@ -0,0 +1,12 @@
|
|||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<urlset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd" xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
|
||||||
|
<url>
|
||||||
|
<loc>https://commonflow.org/spec/1.0.0-rc.1.html</loc>
|
||||||
|
</url>
|
||||||
|
<url>
|
||||||
|
<loc>https://commonflow.org/spec/1.0.0-rc.2.html</loc>
|
||||||
|
</url>
|
||||||
|
<url>
|
||||||
|
<loc>https://commonflow.org/</loc>
|
||||||
|
</url>
|
||||||
|
</urlset>
|
||||||
268
docs/spec/1.0.0-rc.1.html
Normal file
268
docs/spec/1.0.0-rc.1.html
Normal file
@@ -0,0 +1,268 @@
|
|||||||
|
<!DOCTYPE html>
|
||||||
|
<html>
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8">
|
||||||
|
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||||
|
<link href='https://fonts.googleapis.com/css?family=Open+Sans+Condensed:700,300|Open+Sans:400italic,700italic,400,700' rel='stylesheet' type='text/css'>
|
||||||
|
<link rel="stylesheet" href="https://unpkg.com/purecss@1.0.0/build/pure-min.css" integrity="sha384-nn4HPE8lTHyVtfCBi5yW9d20FjT8BJwUXyWZT9InLYax14RDjBj46LmSztkmNP9w" crossorigin="anonymous">
|
||||||
|
<link rel="stylesheet" href="/css/main.css">
|
||||||
|
<!-- Begin Jekyll SEO tag v2.2.3 -->
|
||||||
|
<title>Git Common-Flow 1.0.0-rc.1 | Git Common Flow</title>
|
||||||
|
<meta property="og:title" content="Git Common-Flow 1.0.0-rc.1" />
|
||||||
|
<meta name="author" content="Jim Myhrberg" />
|
||||||
|
<meta property="og:locale" content="en_US" />
|
||||||
|
<meta name="description" content="An attempt to gather a sensible selection of the most common usage patterns of git into a single and concise specification." />
|
||||||
|
<meta property="og:description" content="An attempt to gather a sensible selection of the most common usage patterns of git into a single and concise specification." />
|
||||||
|
<link rel="canonical" href="https://commonflow.org/spec/1.0.0-rc.1.html" />
|
||||||
|
<meta property="og:url" content="https://commonflow.org/spec/1.0.0-rc.1.html" />
|
||||||
|
<meta property="og:site_name" content="Git Common Flow" />
|
||||||
|
<script type="application/ld+json">
|
||||||
|
{"@context":"http://schema.org","@type":"WebPage","headline":"Git Common-Flow 1.0.0-rc.1","author":{"@type":"Person","name":"Jim Myhrberg"},"description":"An attempt to gather a sensible selection of the most common usage patterns of git into a single and concise specification.","url":"https://commonflow.org/spec/1.0.0-rc.1.html"}</script>
|
||||||
|
<!-- End Jekyll SEO tag -->
|
||||||
|
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<div id="layout">
|
||||||
|
<a href="#menu" id="menuLink" class="menu-link">
|
||||||
|
<span></span>
|
||||||
|
</a>
|
||||||
|
<div id="menu">
|
||||||
|
<div class="pure-menu">
|
||||||
|
<ul class="pure-menu-list">
|
||||||
|
<li class="pure-menu-item">
|
||||||
|
<div class="pure-menu-label">Versions:</div>
|
||||||
|
</li>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
<li class="pure-menu-item version-1.0.0-rc.2">
|
||||||
|
<a href="/spec/1.0.0-rc.2.html" class="pure-menu-link">1.0.0-rc.2</a>
|
||||||
|
</li>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
<li class="pure-menu-item version-1.0.0-rc.1 pure-menu-selected">
|
||||||
|
<a href="/spec/1.0.0-rc.1.html" class="pure-menu-link">1.0.0-rc.1</a>
|
||||||
|
</li>
|
||||||
|
|
||||||
|
|
||||||
|
</ul>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div id="main">
|
||||||
|
<div class="content">
|
||||||
|
<h1 id="git-common-flow-100-rc1">Git Common-Flow 1.0.0-rc.1</h1>
|
||||||
|
|
||||||
|
<p><img src="/spec/1.0.0-rc.1.svg" width="100%" /></p>
|
||||||
|
|
||||||
|
<h2 id="summary">Summary</h2>
|
||||||
|
|
||||||
|
<p>Common-Flow is an attempt to gather a sensible selection of the most common
|
||||||
|
usage patterns of git into a single and concise specification. It is based on
|
||||||
|
the <a href="http://scottchacon.com/2011/08/31/github-flow.html">original variant</a>
|
||||||
|
of <a href="https://guides.github.com/introduction/flow/">GitHub Flow</a>, while taking
|
||||||
|
into account how a lot of open source projects use git.</p>
|
||||||
|
|
||||||
|
<p>TL;DR: Common-Flow is basically GitHub Flow with the addition of versioned
|
||||||
|
releases, maintenance releases for old versions, and without the requirement to
|
||||||
|
deploy to production all the time.</p>
|
||||||
|
|
||||||
|
<h2 id="terminology">Terminology</h2>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>Master Branch</strong> - Must always have passing tests, is considered bleeding
|
||||||
|
edge, and must be named <code class="highlighter-rouge">master</code>.</li>
|
||||||
|
<li><strong>Change Branches</strong> - Any branch that introduces changes like a new feature, a
|
||||||
|
bug fix, etc.</li>
|
||||||
|
<li><strong>Source Branch</strong> - The branch that a change branch was created from. New
|
||||||
|
changes in the source branch should be incorporated into the change branch via
|
||||||
|
rebasing.</li>
|
||||||
|
<li><strong>Merge Target</strong> - A branch that is the intended merge target for a change
|
||||||
|
branch. Typically the merge target branch will be the same as the source
|
||||||
|
branch.</li>
|
||||||
|
<li><strong>Maintenance Branches</strong> - Used for maintaining old versions and releasing
|
||||||
|
PATCH updates when the master branch has moved on. Should follow a
|
||||||
|
<code class="highlighter-rouge">stable-X.Y</code> naming pattern, where <code class="highlighter-rouge">X</code> is MAJOR version and <code class="highlighter-rouge">Y</code> is MINOR
|
||||||
|
version.</li>
|
||||||
|
<li><strong>Pull Request</strong> - A means of requesting that a change branch is merged in to
|
||||||
|
its merge target, allowing others to review, discuss and approve the changes.</li>
|
||||||
|
<li><strong>Release</strong> - Consists of a version bump commit directly on the master branch,
|
||||||
|
and a git tag named according to the new version string placed on said commit.</li>
|
||||||
|
<li><strong>Maintenance Release</strong> - Just like a regular release, except the version bump
|
||||||
|
commit and release tag are on a maintenance branch instead of the master
|
||||||
|
branch.</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h2 id="git-common-flow-specification-common-flow">Git Common-Flow Specification (Common-Flow)</h2>
|
||||||
|
|
||||||
|
<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
|
||||||
|
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
|
||||||
|
interpreted as described in <a href="https://tools.ietf.org/html/rfc2119">RFC 2119</a>.</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>The Master Branch
|
||||||
|
<ol>
|
||||||
|
<li>A branch named "master" MUST exist and it MUST be referred to as the
|
||||||
|
"master branch".</li>
|
||||||
|
<li>The master branch MUST be considered bleeding edge.</li>
|
||||||
|
<li>The master branch MUST always be in a non-broken state with its test
|
||||||
|
suite passing.</li>
|
||||||
|
<li>The master branch SHOULD always be in a "as near as possible ready for
|
||||||
|
release/production" state to reduce the friction of creating a new
|
||||||
|
release.</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
<li>Changes
|
||||||
|
<ol>
|
||||||
|
<li>Changes MUST be performed on a separate branch that SHOULD be referred to
|
||||||
|
as a "change branch". All change branches MUST have descriptive names. It
|
||||||
|
is RECOMMENDED that you commit often locally, and you SHOULD regularly
|
||||||
|
push your work to the same named branch on the remote server.</li>
|
||||||
|
<li>When a change branch is created, the branch that it is created from
|
||||||
|
SHOULD be referred to as the "source branch". Each change branch also
|
||||||
|
needs a designated "merge target branch", typically this will be the same
|
||||||
|
as the source branch.</li>
|
||||||
|
<li>Change branches MUST be regularly updated with any changes from their
|
||||||
|
source branch. This MUST be done by rebasing the change branch on top of
|
||||||
|
the source branch. To be clear you MUST NOT merge a source branch into a
|
||||||
|
change branch.</li>
|
||||||
|
<li>After rebasing a change branch on top of its source branch you MUST push
|
||||||
|
the change branch to the remote server. This will require you do a force
|
||||||
|
push, and you SHOULD use the "--force-with-lease" git push option.</li>
|
||||||
|
<li>To merge a change branch into its merge target branch, you MUST open a
|
||||||
|
"pull request" (or equivalent) so others can review and approve your
|
||||||
|
changes.</li>
|
||||||
|
<li>A pull request MUST only be merged when the change branch is up-to-date
|
||||||
|
with its source branch, the test suite is passing, and you and others are
|
||||||
|
happy with the change. This is especially important if the merge target
|
||||||
|
is the master branch.</li>
|
||||||
|
<li>To get feedback, help, or generally just discuss a change branch with
|
||||||
|
others, it is RECOMMENDED you do this by creating a pull request and
|
||||||
|
discuss the changes with others there.</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
<li>Git Best Practices
|
||||||
|
<ol>
|
||||||
|
<li>All commit messages SHOULD follow the Commit Guidelines and format from
|
||||||
|
the official git
|
||||||
|
documentation:
|
||||||
|
<a href="https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project">https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project</a></li>
|
||||||
|
<li>You SHOULD always use "--force-with-lease" when doing a force push. The
|
||||||
|
plain "--force" option is dangerous and destructive. More
|
||||||
|
information:
|
||||||
|
<a href="https://developer.atlassian.com/blog/2015/04/force-with-lease/">https://developer.atlassian.com/blog/2015/04/force-with-lease/</a></li>
|
||||||
|
<li>You SHOULD understand and be comfortable with
|
||||||
|
rebasing: <a href="https://git-scm.com/book/en/v2/Git-Branching-Rebasing">https://git-scm.com/book/en/v2/Git-Branching-Rebasing</a></li>
|
||||||
|
<li>It is RECOMMENDED that you always do "git pull --rebase" instead of "git
|
||||||
|
pull" to avoid unnecessary merge commits. You can make this the default
|
||||||
|
behavior of "git pull" with "git config --global pull.rebase true".</li>
|
||||||
|
<li>It is RECOMMENDED that all branches be merged using "git merge --no-ff".
|
||||||
|
This makes sure the reference to the original branch is kept in the commits,
|
||||||
|
allows one to revert a merge by reverting a single merge commit, and creates
|
||||||
|
a merge commit to mark the integration of the branch with master.</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
<li>Versioning
|
||||||
|
<ol>
|
||||||
|
<li>The project MUST have its version hard-coded somewhere in the
|
||||||
|
code-base. It is RECOMMENDED that this is done in a file called "VERSION"
|
||||||
|
located in the root of the project.</li>
|
||||||
|
<li>If you are using a "VERSION" file in the root of the project, this MUST
|
||||||
|
only contain the exact version string.</li>
|
||||||
|
<li>The version string SHOULD follow the Semantic Versioning
|
||||||
|
(<a href="http://semver.org/">http://semver.org/</a>) format. Use of Semantic Versioning is OPTIONAL,
|
||||||
|
but the version string MUST NOT have a "v" prefix. For example "v2.11.4"
|
||||||
|
is bad, and "2.11.4" is good.</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
<li>Releases
|
||||||
|
<ol>
|
||||||
|
<li>To create a new release, you MUST create a "version bump" commit directly
|
||||||
|
on the master branch which changes the hard-coded version value of the
|
||||||
|
project. The version bump commit MUST have a git tag created on it and
|
||||||
|
named as the exact version string.</li>
|
||||||
|
<li>A version bump commit MUST have a commit message title of "Bump version
|
||||||
|
to VERSION". For example, if the new version string is "2.11.4", the
|
||||||
|
first line of the commit message MUST read: "Bump version to 2.11.4"</li>
|
||||||
|
<li>The release tag on the version bump commit MUST be named exactly the same
|
||||||
|
as the version string. The tag name can OPTIONALLY be prefixed with
|
||||||
|
"v". For example the tag name can be either "2.11.4" or "v2.11.4".</li>
|
||||||
|
<li>It is RECOMMENDED that release tags are lightweight tags, but you can
|
||||||
|
OPTIONALLY use annotated tags if you want to include changelog
|
||||||
|
information in the release tag itself.</li>
|
||||||
|
<li>If you use annotated release tags, the first line of the annotation MUST
|
||||||
|
read "Release VERSION". For example for version "2.11.4" the first line
|
||||||
|
of the tag annotation would read "Release 2.11.4". The second line must
|
||||||
|
be blank, and the changelog MUST start on the third line.</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
<li>Bug Fixes & Rollback
|
||||||
|
<ol>
|
||||||
|
<li>You MUST NOT under any circumstances force push to the master branch.</li>
|
||||||
|
<li>If a change branch which has been merged in to the master branch is found
|
||||||
|
to have a bug in it, the bug fix work MUST be done as a new separate
|
||||||
|
change branch and MUST follow the same workflow as any other change
|
||||||
|
branch.</li>
|
||||||
|
<li>If a change branch is wrongfully merged in to master, or for any other
|
||||||
|
reason the merge must be undone, you MUST undo the merge by reverting the
|
||||||
|
merge commit itself. Effectively creating a new commit that reverses all
|
||||||
|
the relevant changes.</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
<li>Maintenance Releases
|
||||||
|
<ol>
|
||||||
|
<li>Any branch that has a name starting with "stable-" SHOULD be referred to
|
||||||
|
as a "maintenance branch".</li>
|
||||||
|
<li>Maintenance branches are used for managing new releases of older
|
||||||
|
versions. Typically this is used to provide security updates for older
|
||||||
|
versions when the master branch has moved on to a point that a new
|
||||||
|
release for the old version cannot be made from the master branch.</li>
|
||||||
|
<li>A "maintenance release" is identical to a regular release, except the
|
||||||
|
version bump commit and the release tag are placed on the maintenance
|
||||||
|
branch instead of on the master branch.</li>
|
||||||
|
<li>A maintenance branch SHOULD follow a "stable-X.Y" naming pattern, where
|
||||||
|
"X" is the MAJOR version and "Y" is the minor version.</li>
|
||||||
|
<li>A maintenance branch MUST be created from the relevant release tag. For
|
||||||
|
example if there is a security fix for all 2.9.x releases, the latest of
|
||||||
|
which is "2.9.7", we create a new branch called "stable-2.9" off of the
|
||||||
|
"2.9.7" release tag. The security fix release will then end up being
|
||||||
|
version "2.9.8".</li>
|
||||||
|
<li>When working on a maintenance release, the relevant maintenance branch
|
||||||
|
MUST be thought of as the master branch for that maintenance work.</li>
|
||||||
|
<li>Changes in a maintenance branch SHOULD typically come from work being
|
||||||
|
done against the master branch. Meaning changes SHOULD only trickle
|
||||||
|
downwards from the master branch. If a change needs to trickle back up
|
||||||
|
into the master branch, that work should have happened against the master
|
||||||
|
branch in the first place.</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h2 id="about">About</h2>
|
||||||
|
|
||||||
|
<p>The Git Common-Flow specification is authored
|
||||||
|
by <a href="http://jimeh.me">Jim Myhrberg</a>.</p>
|
||||||
|
|
||||||
|
<p>If you'd like to leave feedback,
|
||||||
|
please <a href="https://github.com/jimeh/common-flow/issues">open an issue on GitHub</a>.</p>
|
||||||
|
|
||||||
|
<h2 id="license">License</h2>
|
||||||
|
|
||||||
|
<p><a href="http://creativecommons.org/licenses/by/3.0/">Creative Commons - CC BY 3.0</a></p>
|
||||||
|
|
||||||
|
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<script src="/js/ui.js"></script>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
2
docs/spec/1.0.0-rc.1.svg
Normal file
2
docs/spec/1.0.0-rc.1.svg
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 18 KiB |
302
docs/spec/1.0.0-rc.2.html
Normal file
302
docs/spec/1.0.0-rc.2.html
Normal file
@@ -0,0 +1,302 @@
|
|||||||
|
<!DOCTYPE html>
|
||||||
|
<html>
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8">
|
||||||
|
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||||
|
<link href='https://fonts.googleapis.com/css?family=Open+Sans+Condensed:700,300|Open+Sans:400italic,700italic,400,700' rel='stylesheet' type='text/css'>
|
||||||
|
<link rel="stylesheet" href="https://unpkg.com/purecss@1.0.0/build/pure-min.css" integrity="sha384-nn4HPE8lTHyVtfCBi5yW9d20FjT8BJwUXyWZT9InLYax14RDjBj46LmSztkmNP9w" crossorigin="anonymous">
|
||||||
|
<link rel="stylesheet" href="/css/main.css">
|
||||||
|
<!-- Begin Jekyll SEO tag v2.2.3 -->
|
||||||
|
<title>Git Common-Flow 1.0.0-rc.2 | Git Common Flow</title>
|
||||||
|
<meta property="og:title" content="Git Common-Flow 1.0.0-rc.2" />
|
||||||
|
<meta name="author" content="Jim Myhrberg" />
|
||||||
|
<meta property="og:locale" content="en_US" />
|
||||||
|
<meta name="description" content="An attempt to gather a sensible selection of the most common usage patterns of git into a single and concise specification." />
|
||||||
|
<meta property="og:description" content="An attempt to gather a sensible selection of the most common usage patterns of git into a single and concise specification." />
|
||||||
|
<link rel="canonical" href="https://commonflow.org/spec/1.0.0-rc.2.html" />
|
||||||
|
<meta property="og:url" content="https://commonflow.org/spec/1.0.0-rc.2.html" />
|
||||||
|
<meta property="og:site_name" content="Git Common Flow" />
|
||||||
|
<script type="application/ld+json">
|
||||||
|
{"@context":"http://schema.org","@type":"WebPage","headline":"Git Common-Flow 1.0.0-rc.2","author":{"@type":"Person","name":"Jim Myhrberg"},"description":"An attempt to gather a sensible selection of the most common usage patterns of git into a single and concise specification.","url":"https://commonflow.org/spec/1.0.0-rc.2.html"}</script>
|
||||||
|
<!-- End Jekyll SEO tag -->
|
||||||
|
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<div id="layout">
|
||||||
|
<a href="#menu" id="menuLink" class="menu-link">
|
||||||
|
<span></span>
|
||||||
|
</a>
|
||||||
|
<div id="menu">
|
||||||
|
<div class="pure-menu">
|
||||||
|
<ul class="pure-menu-list">
|
||||||
|
<li class="pure-menu-item">
|
||||||
|
<div class="pure-menu-label">Versions:</div>
|
||||||
|
</li>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
<li class="pure-menu-item version-1.0.0-rc.2 pure-menu-selected">
|
||||||
|
<a href="/spec/1.0.0-rc.2.html" class="pure-menu-link">1.0.0-rc.2</a>
|
||||||
|
</li>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
<li class="pure-menu-item version-1.0.0-rc.1">
|
||||||
|
<a href="/spec/1.0.0-rc.1.html" class="pure-menu-link">1.0.0-rc.1</a>
|
||||||
|
</li>
|
||||||
|
|
||||||
|
|
||||||
|
</ul>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div id="main">
|
||||||
|
<div class="content">
|
||||||
|
<h1 id="git-common-flow-100-rc2">Git Common-Flow 1.0.0-rc.2</h1>
|
||||||
|
|
||||||
|
<p><img src="/spec/1.0.0-rc.2.svg" width="100%" /></p>
|
||||||
|
|
||||||
|
<h2 id="summary">Summary</h2>
|
||||||
|
|
||||||
|
<p>Common-Flow is an attempt to gather a sensible selection of the most common
|
||||||
|
usage patterns of git into a single and concise specification. It is based on
|
||||||
|
the <a href="http://scottchacon.com/2011/08/31/github-flow.html">original variant</a>
|
||||||
|
of <a href="https://guides.github.com/introduction/flow/">GitHub Flow</a>, while taking
|
||||||
|
into account how a lot of open source projects use git.</p>
|
||||||
|
|
||||||
|
<p>TL;DR: Common-Flow is basically GitHub Flow with the addition of versioned
|
||||||
|
releases, maintenance releases for old versions, and without the requirement to
|
||||||
|
deploy to production all the time.</p>
|
||||||
|
|
||||||
|
<h2 id="terminology">Terminology</h2>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>Master Branch</strong> - Must always have passing tests, is considered bleeding
|
||||||
|
edge, and must be named <code class="highlighter-rouge">master</code>.</li>
|
||||||
|
<li><strong>Change Branches</strong> - Any branch that introduces changes like a new feature, a
|
||||||
|
bug fix, etc.</li>
|
||||||
|
<li><strong>Source Branch</strong> - The branch that a change branch was created from. New
|
||||||
|
changes in the source branch should be incorporated into the change branch via
|
||||||
|
rebasing.</li>
|
||||||
|
<li><strong>Merge Target</strong> - A branch that is the intended merge target for a change
|
||||||
|
branch. Typically the merge target branch will be the same as the source
|
||||||
|
branch.</li>
|
||||||
|
<li><strong>Pull Request</strong> - A means of requesting that a change branch is merged in to
|
||||||
|
its merge target, allowing others to review, discuss and approve the changes.</li>
|
||||||
|
<li><strong>Release</strong> - Consists of a version bump commit, and a git tag named according
|
||||||
|
to the new version string placed on said commit.</li>
|
||||||
|
<li><strong>Release Branches</strong> - Used both for short-term preparations of a release, and
|
||||||
|
also for long-term maintenance of older version.</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h2 id="git-common-flow-specification-common-flow">Git Common-Flow Specification (Common-Flow)</h2>
|
||||||
|
|
||||||
|
<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
|
||||||
|
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
|
||||||
|
interpreted as described in <a href="https://tools.ietf.org/html/rfc2119">RFC 2119</a>.</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>The Master Branch
|
||||||
|
<ol>
|
||||||
|
<li>A branch named "master" MUST exist and it MUST be referred to as the
|
||||||
|
"master branch".</li>
|
||||||
|
<li>The master branch MUST be considered bleeding edge.</li>
|
||||||
|
<li>The master branch MUST always be in a non-broken state with its test
|
||||||
|
suite passing.</li>
|
||||||
|
<li>The master branch SHOULD always be in a "as near as possibly ready for
|
||||||
|
release/production" state to reduce any friction with creating a new
|
||||||
|
release.</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
<li>Change Branches
|
||||||
|
<ol>
|
||||||
|
<li>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
|
||||||
|
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
|
||||||
|
SHOULD be referred to as the "source branch". Each change branch also
|
||||||
|
needs a designated "merge target" branch, typically this will be the same
|
||||||
|
as the source branch.</li>
|
||||||
|
<li>Change branches MUST be regularly updated with any changes from their
|
||||||
|
source branch. This MUST be done by rebasing the change branch on top of
|
||||||
|
the source branch.</li>
|
||||||
|
<li>After rebasing a change branch on top of its source branch you MUST push
|
||||||
|
the change branch to the remote server. This will require you to do a
|
||||||
|
force push, and you SHOULD use the "--force-with-lease" git push option.</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
<li>Pull Requests
|
||||||
|
<ol>
|
||||||
|
<li>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
|
||||||
|
with its source branch, the test suite is passing, and you and others are
|
||||||
|
happy with the change. This is especially important if the merge target
|
||||||
|
is the master branch.</li>
|
||||||
|
<li>To get feedback, help, or generally just discuss a change branch with
|
||||||
|
others, the RECOMMENDED way to do so is by creating a pull request and
|
||||||
|
discuss the changes with others there.</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
<li>Versioning
|
||||||
|
<ol>
|
||||||
|
<li>The project MUST have its version hard-coded somewhere in the
|
||||||
|
code-base. It is RECOMMENDED that this is done in a file called "VERSION"
|
||||||
|
located in the root of the project.</li>
|
||||||
|
<li>If you are using a "VERSION" file in the root of the project, this MUST
|
||||||
|
only contain the exact version string.</li>
|
||||||
|
<li>The version string SHOULD follow the Semantic Versioning
|
||||||
|
(<a href="http://semver.org/">http://semver.org/</a>) format. Use of Semantic Versioning is OPTIONAL,
|
||||||
|
but the version string MUST NOT have a "v" prefix. For example "v2.11.4"
|
||||||
|
is bad, and "2.11.4" is good.</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
<li>Releases
|
||||||
|
<ol>
|
||||||
|
<li>To create a new release, you MUST create a "version bump" commit 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
|
||||||
|
be created directly on the master branch.</li>
|
||||||
|
<li>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
|
||||||
|
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
|
||||||
|
OPTIONALLY use annotated tags if you want to include changelog
|
||||||
|
information in the release tag itself.</li>
|
||||||
|
<li>If you use annotated release tags, the first line of the annotation MUST
|
||||||
|
read "Release VERSION". For example for version "2.11.4" the first line
|
||||||
|
of the tag annotation would read "Release 2.11.4". The second line must
|
||||||
|
be blank, and the changelog MUST start on the third line.</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
<li>Release Branches
|
||||||
|
<ol>
|
||||||
|
<li>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
|
||||||
|
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
|
||||||
|
<ol>
|
||||||
|
<li>Used for creating a specific versioned release.</li>
|
||||||
|
<li>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
|
||||||
|
"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
|
||||||
|
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
|
||||||
|
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
|
||||||
|
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
|
||||||
|
<ol>
|
||||||
|
<li>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
|
||||||
|
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
|
||||||
|
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
|
||||||
|
tag. For example if the master branch is on version 2.11.4 and there
|
||||||
|
is a security fix for all 2.9.x releases, the latest of which is
|
||||||
|
"2.9.7". Create a new branch called "release-2.9" off of the "2.9.7"
|
||||||
|
release tag. The security fix release will then end up being version
|
||||||
|
"2.9.8".</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
<li>Bug Fixes & Rollback
|
||||||
|
<ol>
|
||||||
|
<li>You MUST NOT under any circumstances force push to the master branch.</li>
|
||||||
|
<li>If a change branch which has been merged 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
|
||||||
|
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>Git Best Practices
|
||||||
|
<ol>
|
||||||
|
<li>All commit messages SHOULD follow the Commit Guidelines and format from
|
||||||
|
the official git
|
||||||
|
documentation:
|
||||||
|
<a href="https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project">https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project</a></li>
|
||||||
|
<li>You SHOULD 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
|
||||||
|
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
|
||||||
|
rebasing: <a href="https://git-scm.com/book/en/v2/Git-Branching-Rebasing">https://git-scm.com/book/en/v2/Git-Branching-Rebasing</a></li>
|
||||||
|
<li>It is RECOMMENDED that you always do "git pull --rebase" instead of "git
|
||||||
|
pull" to avoid unnecessary merge commits. You can make this the default
|
||||||
|
behavior of "git pull" with "git config --global pull.rebase true".</li>
|
||||||
|
<li>It is RECOMMENDED that all branches be merged using "git merge --no-ff".
|
||||||
|
This makes sure the reference to the original branch is kept in the
|
||||||
|
commits, allows one to revert a merge by reverting a single merge commit,
|
||||||
|
and creates a merge commit to mark the integration of the branch with
|
||||||
|
master.</li>
|
||||||
|
</ol>
|
||||||
|
</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h2 id="about">About</h2>
|
||||||
|
|
||||||
|
<p>The Git Common-Flow specification is authored
|
||||||
|
by <a href="http://jimeh.me">Jim Myhrberg</a>.</p>
|
||||||
|
|
||||||
|
<p>If you'd like to leave feedback,
|
||||||
|
please <a href="https://github.com/jimeh/common-flow/issues">open an issue on GitHub</a>.</p>
|
||||||
|
|
||||||
|
<h2 id="license">License</h2>
|
||||||
|
|
||||||
|
<p><a href="http://creativecommons.org/licenses/by/3.0/">Creative Commons - CC BY 3.0</a></p>
|
||||||
|
|
||||||
|
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<script src="/js/ui.js"></script>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
2
docs/spec/1.0.0-rc.2.svg
Normal file
2
docs/spec/1.0.0-rc.2.svg
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 18 KiB |
213
index.md
213
index.md
@@ -1,11 +1,11 @@
|
|||||||
---
|
---
|
||||||
title: Git Common-Flow 1.0.0-rc.1
|
title: Git Common-Flow 1.0.0-rc.2
|
||||||
version: 1.0.0-rc.1
|
version: 1.0.0-rc.2
|
||||||
---
|
---
|
||||||
Git Common-Flow 1.0.0-rc.1
|
Git Common-Flow 1.0.0-rc.2
|
||||||
==============================
|
==============================
|
||||||
|
|
||||||
<img src="/spec/1.0.0-rc.1.svg" width="100%" />
|
<img src="/spec/1.0.0-rc.2.svg" width="100%" />
|
||||||
|
|
||||||
Summary
|
Summary
|
||||||
-------
|
-------
|
||||||
@@ -33,17 +33,12 @@ Terminology
|
|||||||
- **Merge Target** - A branch that is the intended merge target for a change
|
- **Merge Target** - A branch that is the intended merge target for a change
|
||||||
branch. Typically the merge target branch will be the same as the source
|
branch. Typically the merge target branch will be the same as the source
|
||||||
branch.
|
branch.
|
||||||
- **Maintenance Branches** - Used for maintaining old versions and releasing
|
|
||||||
PATCH updates when the master branch has moved on. Should follow a
|
|
||||||
`stable-X.Y` naming pattern, where `X` is MAJOR version and `Y` is MINOR
|
|
||||||
version.
|
|
||||||
- **Pull Request** - A means of requesting that a change branch is merged in to
|
- **Pull Request** - A means of requesting that a change branch is merged in to
|
||||||
its merge target, allowing others to review, discuss and approve the changes.
|
its merge target, allowing others to review, discuss and approve the changes.
|
||||||
- **Release** - Consists of a version bump commit directly on the master branch,
|
- **Release** - Consists of a version bump commit, and a git tag named according
|
||||||
and a git tag named according to the new version string placed on said commit.
|
to the new version string placed on said commit.
|
||||||
- **Maintenance Release** - Just like a regular release, except the version bump
|
- **Release Branches** - Used both for short-term preparations of a release, and
|
||||||
commit and release tag are on a maintenance branch instead of the master
|
also for long-term maintenance of older version.
|
||||||
branch.
|
|
||||||
|
|
||||||
Git Common-Flow Specification (Common-Flow)
|
Git Common-Flow Specification (Common-Flow)
|
||||||
-------------------------------------------
|
-------------------------------------------
|
||||||
@@ -58,53 +53,38 @@ interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
|
|||||||
2. The master branch MUST be considered bleeding edge.
|
2. The master branch MUST be considered bleeding edge.
|
||||||
3. The master branch MUST always be in a non-broken state with its test
|
3. The master branch MUST always be in a non-broken state with its test
|
||||||
suite passing.
|
suite passing.
|
||||||
4. The master branch SHOULD always be in a "as near as possible ready for
|
4. The master branch SHOULD always be in a "as near as possibly ready for
|
||||||
release/production" state to reduce the friction of creating a new
|
release/production" state to reduce any friction with creating a new
|
||||||
release.
|
release.
|
||||||
2. Changes
|
2. Change Branches
|
||||||
1. Changes MUST be performed on a separate branch that SHOULD be referred to
|
1. Each change (feature, bugfix, etc.) MUST be performed on separate
|
||||||
as a "change branch". All change branches MUST have descriptive names. It
|
branches that SHOULD be referred to as "change branches". All change
|
||||||
is RECOMMENDED that you commit often locally, and you SHOULD regularly
|
branches MUST have descriptive names. It is RECOMMENDED that you commit
|
||||||
push your work to the same named branch on the remote server.
|
often locally, and you SHOULD regularly push your work to the same named
|
||||||
2. When a change branch is created, the branch that it is created from
|
branch on the remote server.
|
||||||
SHOULD be referred to as the "source branch". Each change branch also
|
2. You MUST create separate change branches for each distinctly different
|
||||||
needs a designated "merge target branch", typically this will be the same
|
change. You MUST NOT include multiple unrelated changes into a single
|
||||||
as the source branch.
|
|
||||||
3. Change branches MUST be regularly updated with any changes from their
|
|
||||||
source branch. This MUST be done by rebasing the change branch on top of
|
|
||||||
the source branch. To be clear you MUST NOT merge a source branch into a
|
|
||||||
change branch.
|
change branch.
|
||||||
4. After rebasing a change branch on top of its source branch you MUST push
|
3. When a change branch is created, the branch that it is created from
|
||||||
the change branch to the remote server. This will require you do a force
|
SHOULD be referred to as the "source branch". Each change branch also
|
||||||
push, and you SHOULD use the "--force-with-lease" git push option.
|
needs a designated "merge target" branch, typically this will be the same
|
||||||
5. To merge a change branch into its merge target branch, you MUST open a
|
as the source branch.
|
||||||
"pull request" (or equivalent) so others can review and approve your
|
4. Change branches MUST be regularly updated with any changes from their
|
||||||
changes.
|
source branch. This MUST be done by rebasing the change branch on top of
|
||||||
6. A pull request MUST only be merged when the change branch is up-to-date
|
the source branch.
|
||||||
|
5. After rebasing a change branch on top of its source branch you MUST push
|
||||||
|
the change branch to the remote server. This will require you to do a
|
||||||
|
force push, and you SHOULD use the "--force-with-lease" git push option.
|
||||||
|
3. Pull Requests
|
||||||
|
1. To merge a change branch into its merge target, you MUST open a "pull
|
||||||
|
request" (or equivalent) so others can review and approve your changes.
|
||||||
|
2. A pull request MUST only be merged when the change branch is up-to-date
|
||||||
with its source branch, the test suite is passing, and you and others are
|
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
|
happy with the change. This is especially important if the merge target
|
||||||
is the master branch.
|
is the master branch.
|
||||||
7. To get feedback, help, or generally just discuss a change branch with
|
3. 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
|
others, the RECOMMENDED way to do so is by creating a pull request and
|
||||||
discuss the changes with others there.
|
discuss the changes with others there.
|
||||||
3. Git Best Practices
|
|
||||||
1. All commit messages SHOULD follow the Commit Guidelines and format from
|
|
||||||
the official git
|
|
||||||
documentation:
|
|
||||||
<https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project>
|
|
||||||
2. You SHOULD always use "--force-with-lease" when doing a force push. The
|
|
||||||
plain "--force" option is dangerous and destructive. More
|
|
||||||
information:
|
|
||||||
<https://developer.atlassian.com/blog/2015/04/force-with-lease/>
|
|
||||||
3. You SHOULD understand and be comfortable with
|
|
||||||
rebasing: <https://git-scm.com/book/en/v2/Git-Branching-Rebasing>
|
|
||||||
4. It is RECOMMENDED that you always do "git pull --rebase" instead of "git
|
|
||||||
pull" to avoid unnecessary merge commits. You can make this the default
|
|
||||||
behavior of "git pull" with "git config --global pull.rebase true".
|
|
||||||
5. It is RECOMMENDED that all branches be merged using "git merge --no-ff".
|
|
||||||
This makes sure the reference to the original branch is kept in the commits,
|
|
||||||
allows one to revert a merge by reverting a single merge commit, and creates
|
|
||||||
a merge commit to mark the integration of the branch with master.
|
|
||||||
4. Versioning
|
4. Versioning
|
||||||
1. The project MUST have its version hard-coded somewhere in the
|
1. The project MUST have its version hard-coded somewhere in the
|
||||||
code-base. It is RECOMMENDED that this is done in a file called "VERSION"
|
code-base. It is RECOMMENDED that this is done in a file called "VERSION"
|
||||||
@@ -116,57 +96,102 @@ interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
|
|||||||
but the version string MUST NOT have a "v" prefix. For example "v2.11.4"
|
but the version string MUST NOT have a "v" prefix. For example "v2.11.4"
|
||||||
is bad, and "2.11.4" is good.
|
is bad, and "2.11.4" is good.
|
||||||
5. Releases
|
5. Releases
|
||||||
1. To create a new release, you MUST create a "version bump" commit directly
|
1. To create a new release, you MUST create a "version bump" commit which
|
||||||
on the master branch which changes the hard-coded version value of the
|
changes the hard-coded version string of the project. The version bump
|
||||||
project. The version bump commit MUST have a git tag created on it and
|
commit MUST have a git tag created on it and named as the exact version
|
||||||
named as the exact version string.
|
string.
|
||||||
2. A version bump commit MUST have a commit message title of "Bump version
|
2. If you are not using a release branch, then the version bump commit MUST
|
||||||
|
be created directly on the master branch.
|
||||||
|
3. The version bump commit MUST have a commit message title of "Bump version
|
||||||
to VERSION". For example, if the new version string is "2.11.4", the
|
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"
|
first line of the commit message MUST read: "Bump version to 2.11.4"
|
||||||
3. The release tag on the version bump commit MUST be named exactly the same
|
4. The release tag on the version bump commit MUST be named exactly the same
|
||||||
as the version string. The tag name can OPTIONALLY be prefixed with
|
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".
|
"v". For example the tag name can be either "2.11.4" or "v2.11.4". You
|
||||||
4. It is RECOMMENDED that release tags are lightweight tags, but you can
|
MUST not use a mix of "v" prefixed and non-prefixed tags. Pick one form
|
||||||
|
and stick to it.
|
||||||
|
5. It is RECOMMENDED that release tags are lightweight tags, but you can
|
||||||
OPTIONALLY use annotated tags if you want to include changelog
|
OPTIONALLY use annotated tags if you want to include changelog
|
||||||
information in the release tag itself.
|
information in the release tag itself.
|
||||||
5. If you use annotated release tags, the first line of the annotation MUST
|
6. If you use annotated release tags, the first line of the annotation MUST
|
||||||
read "Release VERSION". For example for version "2.11.4" the first line
|
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
|
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.
|
be blank, and the changelog MUST start on the third line.
|
||||||
6. Bug Fixes & Rollback
|
6. Release Branches
|
||||||
1. You MUST NOT under any circumstances force push to the master branch.
|
1. Any branch that has a name starting with "release-" SHOULD be referred to
|
||||||
2. If a change branch which has been merged in to the master branch is found
|
as a "release branch".
|
||||||
to have a bug in it, the bug fix work MUST be done as a new separate
|
2. Use of release branches is OPTIONAL.
|
||||||
change branch and MUST follow the same workflow as any other change
|
3. Changes in a release branch SHOULD typically come from work being
|
||||||
branch.
|
|
||||||
3. 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.
|
|
||||||
7. Maintenance Releases
|
|
||||||
1. Any branch that has a name starting with "stable-" SHOULD be referred to
|
|
||||||
as a "maintenance branch".
|
|
||||||
2. 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.
|
|
||||||
3. 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.
|
|
||||||
3. A maintenance branch SHOULD follow a "stable-X.Y" naming pattern, where
|
|
||||||
"X" is the MAJOR version and "Y" is the minor version.
|
|
||||||
4. 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".
|
|
||||||
5. When working on a maintenance release, the relevant maintenance branch
|
|
||||||
MUST be thought of as the master branch for that maintenance work.
|
|
||||||
6. Changes in a maintenance branch SHOULD typically come from work being
|
|
||||||
done against the master branch. Meaning changes SHOULD only trickle
|
done against the master branch. Meaning changes SHOULD only trickle
|
||||||
downwards from the master branch. If a change needs to trickle back up
|
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
|
into the master branch, that work should have happened against the master
|
||||||
branch in the first place.
|
branch in the first place. One exception to this is version bump commits.
|
||||||
|
4. There are two types of release branches; short-term, and long-term.
|
||||||
|
5. Short-Term Release Branches
|
||||||
|
1. Used for creating a specific versioned release.
|
||||||
|
2. A short-term release branch is RECOMMENDED if there is a lengthy
|
||||||
|
pre-release verification process to avoid a code freeze on the master
|
||||||
|
branch.
|
||||||
|
3. MUST have a name of "release-VERSION". For example for version
|
||||||
|
"2.11.4" the release branch name MUST be "release-2.11.4".
|
||||||
|
4. When using a short-term release branch, the version bump commit and
|
||||||
|
release tag MUST be made directly on the release branch itself.
|
||||||
|
5. Only very minor changes should be performed on a short-term release
|
||||||
|
branch directly. Any larger changes SHOULD be done in the master
|
||||||
|
branch, and SHOULD be pulled into the release branch by rebasing it
|
||||||
|
on top of the master branch the same way a change branch pulls in
|
||||||
|
updates from its source branch.
|
||||||
|
6. After the version bump commit and release tag have been created, the
|
||||||
|
release branch MUST be merged back into its source branch and then
|
||||||
|
deleted. Typically the source branch will be the master branch.
|
||||||
|
6. Long-Term Release Branches
|
||||||
|
1. Used for work on versions which are not currently part of the master
|
||||||
|
branch. Typically this is useful when you need to create a new
|
||||||
|
maintenance release for a older version.
|
||||||
|
2. The branch name MUST have a non-specific version number. For example
|
||||||
|
a long-term release branch for creating new 2.9.x releases would be
|
||||||
|
named "release-2.9".
|
||||||
|
3. To create a new release from a long-term release branch, you MUST
|
||||||
|
create a version bump commit and release tag directly on the release
|
||||||
|
branch.
|
||||||
|
4. A long-term release branch MUST be created from the relevant release
|
||||||
|
tag. For example if the master branch is on version 2.11.4 and there
|
||||||
|
is a security fix for all 2.9.x releases, the latest of which is
|
||||||
|
"2.9.7". Create a new branch called "release-2.9" off of the "2.9.7"
|
||||||
|
release tag. The security fix release will then end up being version
|
||||||
|
"2.9.8".
|
||||||
|
7. Bug Fixes & Rollback
|
||||||
|
1. You MUST NOT under any circumstances force push to the master branch.
|
||||||
|
2. If a change branch which has been merged into the master branch is found
|
||||||
|
to have a bug in it, the bug fix work MUST be done as a new separate
|
||||||
|
change branch and MUST follow the same workflow as any other change
|
||||||
|
branch.
|
||||||
|
3. If a change branch is wrongfully merged into master, or for any other
|
||||||
|
reason the merge must be undone, you MUST undo the merge by reverting the
|
||||||
|
merge commit itself. Effectively creating a new commit that reverses all
|
||||||
|
the relevant changes.
|
||||||
|
8. Git Best Practices
|
||||||
|
1. All commit messages SHOULD follow the Commit Guidelines and format from
|
||||||
|
the official git
|
||||||
|
documentation:
|
||||||
|
<https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project>
|
||||||
|
2. You SHOULD never blindly commit all changes with "git commit -a". It is
|
||||||
|
RECOMMENDED you use "git add -i" to add individual changes to the staging
|
||||||
|
area so you are fully aware of what you are committing.
|
||||||
|
3. You SHOULD always use "--force-with-lease" when doing a force push. The
|
||||||
|
regular "--force" option is dangerous and destructive. More
|
||||||
|
information:
|
||||||
|
<https://developer.atlassian.com/blog/2015/04/force-with-lease/>
|
||||||
|
4. You SHOULD understand and be comfortable with
|
||||||
|
rebasing: <https://git-scm.com/book/en/v2/Git-Branching-Rebasing>
|
||||||
|
5. It is RECOMMENDED that you always do "git pull --rebase" instead of "git
|
||||||
|
pull" to avoid unnecessary merge commits. You can make this the default
|
||||||
|
behavior of "git pull" with "git config --global pull.rebase true".
|
||||||
|
6. It is RECOMMENDED that all branches be merged using "git merge --no-ff".
|
||||||
|
This makes sure the reference to the original branch is kept in the
|
||||||
|
commits, allows one to revert a merge by reverting a single merge commit,
|
||||||
|
and creates a merge commit to mark the integration of the branch with
|
||||||
|
master.
|
||||||
|
|
||||||
About
|
About
|
||||||
-----
|
-----
|
||||||
|
|||||||
209
spec/1.0.0-rc.2.md
Normal file
209
spec/1.0.0-rc.2.md
Normal file
@@ -0,0 +1,209 @@
|
|||||||
|
---
|
||||||
|
title: Git Common-Flow 1.0.0-rc.2
|
||||||
|
version: 1.0.0-rc.2
|
||||||
|
---
|
||||||
|
Git Common-Flow 1.0.0-rc.2
|
||||||
|
==============================
|
||||||
|
|
||||||
|
<img src="/spec/1.0.0-rc.2.svg" width="100%" />
|
||||||
|
|
||||||
|
Summary
|
||||||
|
-------
|
||||||
|
|
||||||
|
Common-Flow is an attempt to gather a sensible selection of the most common
|
||||||
|
usage patterns of git into a single and concise specification. It is based on
|
||||||
|
the [original variant](http://scottchacon.com/2011/08/31/github-flow.html)
|
||||||
|
of [GitHub Flow](https://guides.github.com/introduction/flow/), while taking
|
||||||
|
into account how a lot of open source projects use git.
|
||||||
|
|
||||||
|
TL;DR: Common-Flow is basically GitHub Flow with the addition of versioned
|
||||||
|
releases, maintenance releases for old versions, and without the requirement to
|
||||||
|
deploy to production all the time.
|
||||||
|
|
||||||
|
Terminology
|
||||||
|
-----------
|
||||||
|
|
||||||
|
- **Master Branch** - Must always have passing tests, is considered bleeding
|
||||||
|
edge, and must be named `master`.
|
||||||
|
- **Change Branches** - Any branch that introduces changes like a new feature, a
|
||||||
|
bug fix, etc.
|
||||||
|
- **Source Branch** - The branch that a change branch was created from. New
|
||||||
|
changes in the source branch should be incorporated into the change branch via
|
||||||
|
rebasing.
|
||||||
|
- **Merge Target** - A branch that is the intended merge target for a change
|
||||||
|
branch. Typically the merge target branch will be the same as the source
|
||||||
|
branch.
|
||||||
|
- **Pull Request** - A means of requesting that a change branch is merged in to
|
||||||
|
its merge target, allowing others to review, discuss and approve the changes.
|
||||||
|
- **Release** - Consists of a version bump commit, and a git tag named according
|
||||||
|
to the new version string placed on said commit.
|
||||||
|
- **Release Branches** - Used both for short-term preparations of a release, and
|
||||||
|
also for long-term maintenance of older version.
|
||||||
|
|
||||||
|
Git Common-Flow Specification (Common-Flow)
|
||||||
|
-------------------------------------------
|
||||||
|
|
||||||
|
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
|
||||||
|
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
|
||||||
|
interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
|
||||||
|
|
||||||
|
1. The Master Branch
|
||||||
|
1. A branch named "master" MUST exist and it MUST be referred to as the
|
||||||
|
"master branch".
|
||||||
|
2. The master branch MUST be considered bleeding edge.
|
||||||
|
3. The master branch MUST always be in a non-broken state with its test
|
||||||
|
suite passing.
|
||||||
|
4. The master branch SHOULD always be in a "as near as possibly ready for
|
||||||
|
release/production" state to reduce any friction with creating a new
|
||||||
|
release.
|
||||||
|
2. Change Branches
|
||||||
|
1. Each change (feature, bugfix, etc.) MUST be performed on separate
|
||||||
|
branches that SHOULD be referred to as "change branches". All change
|
||||||
|
branches MUST have descriptive names. It is RECOMMENDED that you commit
|
||||||
|
often locally, and you SHOULD regularly push your work to the same named
|
||||||
|
branch on the remote server.
|
||||||
|
2. You MUST create separate change branches for each distinctly different
|
||||||
|
change. You MUST NOT include multiple unrelated changes into a single
|
||||||
|
change branch.
|
||||||
|
3. When a change branch is created, the branch that it is created from
|
||||||
|
SHOULD be referred to as the "source branch". Each change branch also
|
||||||
|
needs a designated "merge target" branch, typically this will be the same
|
||||||
|
as the source branch.
|
||||||
|
4. Change branches MUST be regularly updated with any changes from their
|
||||||
|
source branch. This MUST be done by rebasing the change branch on top of
|
||||||
|
the source branch.
|
||||||
|
5. After rebasing a change branch on top of its source branch you MUST push
|
||||||
|
the change branch to the remote server. This will require you to do a
|
||||||
|
force push, and you SHOULD use the "--force-with-lease" git push option.
|
||||||
|
3. Pull Requests
|
||||||
|
1. To merge a change branch into its merge target, you MUST open a "pull
|
||||||
|
request" (or equivalent) so others can review and approve your changes.
|
||||||
|
2. A pull request MUST only be merged when the change branch is up-to-date
|
||||||
|
with its source branch, the test suite is passing, and you and others are
|
||||||
|
happy with the change. This is especially important if the merge target
|
||||||
|
is the master branch.
|
||||||
|
3. To get feedback, help, or generally just discuss a change branch with
|
||||||
|
others, the RECOMMENDED way to do so is by creating a pull request and
|
||||||
|
discuss the changes with others there.
|
||||||
|
4. Versioning
|
||||||
|
1. The project MUST have its version hard-coded somewhere in the
|
||||||
|
code-base. It is RECOMMENDED that this is done in a file called "VERSION"
|
||||||
|
located in the root of the project.
|
||||||
|
2. If you are using a "VERSION" file in the root of the project, this MUST
|
||||||
|
only contain the exact version string.
|
||||||
|
3. The version string SHOULD follow the Semantic Versioning
|
||||||
|
(<http://semver.org/>) format. Use of Semantic Versioning is OPTIONAL,
|
||||||
|
but the version string MUST NOT have a "v" prefix. For example "v2.11.4"
|
||||||
|
is bad, and "2.11.4" is good.
|
||||||
|
5. Releases
|
||||||
|
1. To create a new release, you MUST create a "version bump" commit which
|
||||||
|
changes the hard-coded version string of the project. The version bump
|
||||||
|
commit MUST have a git tag created on it and named as the exact version
|
||||||
|
string.
|
||||||
|
2. If you are not using a release branch, then the version bump commit MUST
|
||||||
|
be created directly on the master branch.
|
||||||
|
3. The version bump commit MUST have a commit message title of "Bump version
|
||||||
|
to VERSION". For example, if the new version string is "2.11.4", the
|
||||||
|
first line of the commit message MUST read: "Bump version to 2.11.4"
|
||||||
|
4. The release tag on the version bump commit MUST be named exactly the same
|
||||||
|
as the version string. The tag name can OPTIONALLY be prefixed with
|
||||||
|
"v". For example the tag name can be either "2.11.4" or "v2.11.4". You
|
||||||
|
MUST not use a mix of "v" prefixed and non-prefixed tags. Pick one form
|
||||||
|
and stick to it.
|
||||||
|
5. It is RECOMMENDED that release tags are lightweight tags, but you can
|
||||||
|
OPTIONALLY use annotated tags if you want to include changelog
|
||||||
|
information in the release tag itself.
|
||||||
|
6. If you use annotated release tags, the first line of the annotation MUST
|
||||||
|
read "Release VERSION". For example for version "2.11.4" the first line
|
||||||
|
of the tag annotation would read "Release 2.11.4". The second line must
|
||||||
|
be blank, and the changelog MUST start on the third line.
|
||||||
|
6. Release Branches
|
||||||
|
1. Any branch that has a name starting with "release-" SHOULD be referred to
|
||||||
|
as a "release branch".
|
||||||
|
2. Use of release branches is OPTIONAL.
|
||||||
|
3. Changes in a release branch SHOULD typically come from work being
|
||||||
|
done against the master branch. Meaning changes SHOULD only trickle
|
||||||
|
downwards from the master branch. If a change needs to trickle back up
|
||||||
|
into the master branch, that work should have happened against the master
|
||||||
|
branch in the first place. One exception to this is version bump commits.
|
||||||
|
4. There are two types of release branches; short-term, and long-term.
|
||||||
|
5. Short-Term Release Branches
|
||||||
|
1. Used for creating a specific versioned release.
|
||||||
|
2. A short-term release branch is RECOMMENDED if there is a lengthy
|
||||||
|
pre-release verification process to avoid a code freeze on the master
|
||||||
|
branch.
|
||||||
|
3. MUST have a name of "release-VERSION". For example for version
|
||||||
|
"2.11.4" the release branch name MUST be "release-2.11.4".
|
||||||
|
4. When using a short-term release branch, the version bump commit and
|
||||||
|
release tag MUST be made directly on the release branch itself.
|
||||||
|
5. Only very minor changes should be performed on a short-term release
|
||||||
|
branch directly. Any larger changes SHOULD be done in the master
|
||||||
|
branch, and SHOULD be pulled into the release branch by rebasing it
|
||||||
|
on top of the master branch the same way a change branch pulls in
|
||||||
|
updates from its source branch.
|
||||||
|
6. After the version bump commit and release tag have been created, the
|
||||||
|
release branch MUST be merged back into its source branch and then
|
||||||
|
deleted. Typically the source branch will be the master branch.
|
||||||
|
6. Long-Term Release Branches
|
||||||
|
1. Used for work on versions which are not currently part of the master
|
||||||
|
branch. Typically this is useful when you need to create a new
|
||||||
|
maintenance release for a older version.
|
||||||
|
2. The branch name MUST have a non-specific version number. For example
|
||||||
|
a long-term release branch for creating new 2.9.x releases would be
|
||||||
|
named "release-2.9".
|
||||||
|
3. To create a new release from a long-term release branch, you MUST
|
||||||
|
create a version bump commit and release tag directly on the release
|
||||||
|
branch.
|
||||||
|
4. A long-term release branch MUST be created from the relevant release
|
||||||
|
tag. For example if the master branch is on version 2.11.4 and there
|
||||||
|
is a security fix for all 2.9.x releases, the latest of which is
|
||||||
|
"2.9.7". Create a new branch called "release-2.9" off of the "2.9.7"
|
||||||
|
release tag. The security fix release will then end up being version
|
||||||
|
"2.9.8".
|
||||||
|
7. Bug Fixes & Rollback
|
||||||
|
1. You MUST NOT under any circumstances force push to the master branch.
|
||||||
|
2. If a change branch which has been merged into the master branch is found
|
||||||
|
to have a bug in it, the bug fix work MUST be done as a new separate
|
||||||
|
change branch and MUST follow the same workflow as any other change
|
||||||
|
branch.
|
||||||
|
3. If a change branch is wrongfully merged into master, or for any other
|
||||||
|
reason the merge must be undone, you MUST undo the merge by reverting the
|
||||||
|
merge commit itself. Effectively creating a new commit that reverses all
|
||||||
|
the relevant changes.
|
||||||
|
8. Git Best Practices
|
||||||
|
1. All commit messages SHOULD follow the Commit Guidelines and format from
|
||||||
|
the official git
|
||||||
|
documentation:
|
||||||
|
<https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project>
|
||||||
|
2. You SHOULD never blindly commit all changes with "git commit -a". It is
|
||||||
|
RECOMMENDED you use "git add -i" to add individual changes to the staging
|
||||||
|
area so you are fully aware of what you are committing.
|
||||||
|
3. You SHOULD always use "--force-with-lease" when doing a force push. The
|
||||||
|
regular "--force" option is dangerous and destructive. More
|
||||||
|
information:
|
||||||
|
<https://developer.atlassian.com/blog/2015/04/force-with-lease/>
|
||||||
|
4. You SHOULD understand and be comfortable with
|
||||||
|
rebasing: <https://git-scm.com/book/en/v2/Git-Branching-Rebasing>
|
||||||
|
5. It is RECOMMENDED that you always do "git pull --rebase" instead of "git
|
||||||
|
pull" to avoid unnecessary merge commits. You can make this the default
|
||||||
|
behavior of "git pull" with "git config --global pull.rebase true".
|
||||||
|
6. It is RECOMMENDED that all branches be merged using "git merge --no-ff".
|
||||||
|
This makes sure the reference to the original branch is kept in the
|
||||||
|
commits, allows one to revert a merge by reverting a single merge commit,
|
||||||
|
and creates a merge commit to mark the integration of the branch with
|
||||||
|
master.
|
||||||
|
|
||||||
|
About
|
||||||
|
-----
|
||||||
|
|
||||||
|
The Git Common-Flow specification is authored
|
||||||
|
by [Jim Myhrberg](http://jimeh.me).
|
||||||
|
|
||||||
|
If you'd like to leave feedback,
|
||||||
|
please [open an issue on GitHub](https://github.com/jimeh/common-flow/issues).
|
||||||
|
|
||||||
|
License
|
||||||
|
-------
|
||||||
|
|
||||||
|
[Creative Commons - CC BY 3.0](http://creativecommons.org/licenses/by/3.0/)
|
||||||
|
|
||||||
2
spec/1.0.0-rc.2.svg
Normal file
2
spec/1.0.0-rc.2.svg
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 18 KiB |
Reference in New Issue
Block a user