From 16b712926c8666c3ef634abbac8404f09eab89ee Mon Sep 17 00:00:00 2001 From: Jim Myhrberg Date: Mon, 3 Jul 2017 14:55:57 +0100 Subject: [PATCH] Initial commit --- .gitignore | 3 + 404.html | 8 ++ Gemfile | 25 ++++ Gemfile.lock | 56 ++++++++ _config.yml | 24 ++++ _layouts/default.html | 53 ++++++++ _sass/base.scss | 46 +++++++ _sass/side-menu-old-ie.scss | 255 ++++++++++++++++++++++++++++++++++++ _sass/side-menu.scss | 248 +++++++++++++++++++++++++++++++++++ css/main-old-ie.scss | 9 ++ css/main.scss | 9 ++ index.md | 179 +++++++++++++++++++++++++ js/ui.js | 46 +++++++ spec/1.0.0-draft.9.md | 179 +++++++++++++++++++++++++ 14 files changed, 1140 insertions(+) create mode 100644 .gitignore create mode 100644 404.html create mode 100644 Gemfile create mode 100644 Gemfile.lock create mode 100644 _config.yml create mode 100644 _layouts/default.html create mode 100644 _sass/base.scss create mode 100644 _sass/side-menu-old-ie.scss create mode 100644 _sass/side-menu.scss create mode 100644 css/main-old-ie.scss create mode 100644 css/main.scss create mode 100644 index.md create mode 100644 js/ui.js create mode 100644 spec/1.0.0-draft.9.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..45c1505 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +_site +.sass-cache +.jekyll-metadata diff --git a/404.html b/404.html new file mode 100644 index 0000000..66c9fa6 --- /dev/null +++ b/404.html @@ -0,0 +1,8 @@ +--- +title: 404 Page Not Found +--- +
+

404

+

Page not found :(

+

The requested page could not be found.

+
diff --git a/Gemfile b/Gemfile new file mode 100644 index 0000000..4006953 --- /dev/null +++ b/Gemfile @@ -0,0 +1,25 @@ +source 'https://rubygems.org' + +# Hello! This is where you manage which Jekyll version is used to run. +# When you want to use a different version, change it below, save the +# file and run `bundle install`. Run Jekyll with `bundle exec`, like so: +# +# bundle exec jekyll serve +# +# This will help ensure the proper Jekyll version is running. +# Happy Jekylling! +gem 'jekyll', '3.5.0' +gem 'redcarpet' + +# If you want to use GitHub Pages, remove the "gem "jekyll"" above and +# uncomment the line below. To upgrade, run `bundle update github-pages`. +# gem "github-pages", group: :jekyll_plugins + +# If you have any plugins, put them here! +group :jekyll_plugins do + gem 'jekyll-sitemap' + gem 'jekyll-seo-tag' +end + +# Windows does not include zoneinfo files, so bundle the tzinfo-data gem +gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby] diff --git a/Gemfile.lock b/Gemfile.lock new file mode 100644 index 0000000..bd30709 --- /dev/null +++ b/Gemfile.lock @@ -0,0 +1,56 @@ +GEM + remote: https://rubygems.org/ + specs: + addressable (2.5.1) + public_suffix (~> 2.0, >= 2.0.2) + colorator (1.1.0) + ffi (1.9.18) + forwardable-extended (2.6.0) + jekyll (3.5.0) + addressable (~> 2.4) + colorator (~> 1.0) + jekyll-sass-converter (~> 1.0) + jekyll-watch (~> 1.1) + kramdown (~> 1.3) + liquid (~> 4.0) + mercenary (~> 0.3.3) + pathutil (~> 0.9) + rouge (~> 1.7) + safe_yaml (~> 1.0) + jekyll-sass-converter (1.5.0) + sass (~> 3.4) + jekyll-seo-tag (2.2.3) + jekyll (~> 3.3) + jekyll-sitemap (1.1.1) + jekyll (~> 3.3) + jekyll-watch (1.5.0) + listen (~> 3.0, < 3.1) + kramdown (1.14.0) + liquid (4.0.0) + listen (3.0.8) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + mercenary (0.3.6) + pathutil (0.14.0) + forwardable-extended (~> 2.6) + public_suffix (2.0.5) + rb-fsevent (0.10.2) + rb-inotify (0.9.10) + ffi (>= 0.5.0, < 2) + redcarpet (3.4.0) + rouge (1.11.1) + safe_yaml (1.0.4) + sass (3.4.24) + +PLATFORMS + ruby + +DEPENDENCIES + jekyll (= 3.5.0) + jekyll-seo-tag + jekyll-sitemap + redcarpet + tzinfo-data + +BUNDLED WITH + 1.14.6 diff --git a/_config.yml b/_config.yml new file mode 100644 index 0000000..59d0643 --- /dev/null +++ b/_config.yml @@ -0,0 +1,24 @@ +title: Git Common Flow +description: > + An attempt to gather a sensible selection of the most common usage patterns of + git into a single and concise specification. +author: Jim Myhrberg + +current_version: 1.0.0-draft.9 +versions: + - 1.0.0-draft.9 + +plugins: + - jekyll-sitemap + - jekyll-seo-tag + +defaults: + - + scope: + path: "" + values: + layout: "default" + +markdown: redcarpet +redcarpet: + extensions: ['autolink'] diff --git a/_layouts/default.html b/_layouts/default.html new file mode 100644 index 0000000..2fbbddc --- /dev/null +++ b/_layouts/default.html @@ -0,0 +1,53 @@ + + + + + + + + + + + + + {% seo %} + + +
+ + + + + +
+
+ {{ content }} +
+
+
+ + + diff --git a/_sass/base.scss b/_sass/base.scss new file mode 100644 index 0000000..a3ef2bd --- /dev/null +++ b/_sass/base.scss @@ -0,0 +1,46 @@ +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; +} + +.content { + margin-top: 80px; +} + +.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; +} diff --git a/_sass/side-menu-old-ie.scss b/_sass/side-menu-old-ie.scss new file mode 100644 index 0000000..5cfc146 --- /dev/null +++ b/_sass/side-menu-old-ie.scss @@ -0,0 +1,255 @@ +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 `
` 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 `
` 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` `
` is the parent `
` 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 `
  • `. + */ + +#menu .pure-menu-selected, +#menu .pure-menu-heading { + background: #1f8dd6; +} + +/* + This styles a link within a selected menu item `
  • `. + */ + +#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; +} \ No newline at end of file diff --git a/_sass/side-menu.scss b/_sass/side-menu.scss new file mode 100644 index 0000000..7abd61c --- /dev/null +++ b/_sass/side-menu.scss @@ -0,0 +1,248 @@ +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 `
    ` 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 `
    ` 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` `
    ` is the parent `
    ` 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 `
  • `. + */ + #menu .pure-menu-selected, + #menu .pure-menu-heading { + background: #1f8dd6; + } + /* + This styles a link within a selected menu item `
  • `. + */ + #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; + } +} diff --git a/css/main-old-ie.scss b/css/main-old-ie.scss new file mode 100644 index 0000000..0d2287f --- /dev/null +++ b/css/main-old-ie.scss @@ -0,0 +1,9 @@ +--- +layout: none +--- + +// Import partials from `sass_dir` (defaults to `_sass`) +@import + "side-menu-old-ie", + "base" +; diff --git a/css/main.scss b/css/main.scss new file mode 100644 index 0000000..9f27033 --- /dev/null +++ b/css/main.scss @@ -0,0 +1,9 @@ +--- +layout: none +--- + +// Import partials from `sass_dir` (defaults to `_sass`) +@import + "side-menu", + "base" +; diff --git a/index.md b/index.md new file mode 100644 index 0000000..79052ed --- /dev/null +++ b/index.md @@ -0,0 +1,179 @@ +--- +title: Git Common-Flow 1.0.0-draft.9 +version: 1.0.0-draft.9 +--- +Git Common-Flow 1.0.0-draft.9 +============================= + +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. +- **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 + its merge target, allowing others to review, discuss and approve the changes. +- **Release** - 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. +- **Maintenance Release** - Just like a regular release, except the version bump + commit and release tag are on a maintenance branch instead of the master + branch. + +Git Common-Flow Specification (Common-Flow) +------------------------------------------- + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). + +1. The Master Branch + 1. A branch named "master" MUST exist and it MUST be referred to as the + "master branch". + 2. The master branch MUST be considered bleeding edge. + 3. The master branch MUST always be in a non-broken state with its test + suite passing. + 4. The master branch SHOULD always be in a "as near as possible ready for + release/production" state to reduce the friction of creating a new + release. +2. Changes + 1. Changes MUST be performed on a separate branch that SHOULD be referred to + as a "change branch". All change branches MUST have descriptive names. It + is RECOMMENDED that you commit often locally, and you SHOULD regularly + push your work to the same named branch on the remote server. + 2. When a change branch is created, the branch that it is created from + SHOULD be referred to as the "source branch". Each change branch also + needs a designated "merge target branch", typically this will be the same + as the source branch. + 3. Change branches MUST be regularly updated with any changes from their + source branch. This MUST be done by rebasing the change branch on top of + the source branch. To be clear you MUST NOT merge a source branch into a + change branch. + 4. After rebasing a change branch on top of its source branch you MUST push + the change branch to the remote server. This will require you do a force + push, and you SHOULD use the "--force-with-lease" git push option. + 5. To merge a change branch into its merge target branch, you MUST open a + "pull request" (or equivalent) so others can review and approve your + changes. + 6. A pull request MUST only be merged when the change branch is up-to-date + with its source branch, the test suite is passing, and you and others are + happy with the change. This is especially important if the merge target + is the master branch. + 7. To get feedback, help, or generally just discuss a change branch with + others, it is RECOMMENDED you do this by creating a pull request and + discuss the changes with others there. +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 + 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 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. + 2. 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" + 3. 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". + 4. 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. + 5. 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. 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 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. + 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 + 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. + +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/) diff --git a/js/ui.js b/js/ui.js new file mode 100644 index 0000000..6d7c20b --- /dev/null +++ b/js/ui.js @@ -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)); diff --git a/spec/1.0.0-draft.9.md b/spec/1.0.0-draft.9.md new file mode 100644 index 0000000..79052ed --- /dev/null +++ b/spec/1.0.0-draft.9.md @@ -0,0 +1,179 @@ +--- +title: Git Common-Flow 1.0.0-draft.9 +version: 1.0.0-draft.9 +--- +Git Common-Flow 1.0.0-draft.9 +============================= + +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. +- **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 + its merge target, allowing others to review, discuss and approve the changes. +- **Release** - 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. +- **Maintenance Release** - Just like a regular release, except the version bump + commit and release tag are on a maintenance branch instead of the master + branch. + +Git Common-Flow Specification (Common-Flow) +------------------------------------------- + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). + +1. The Master Branch + 1. A branch named "master" MUST exist and it MUST be referred to as the + "master branch". + 2. The master branch MUST be considered bleeding edge. + 3. The master branch MUST always be in a non-broken state with its test + suite passing. + 4. The master branch SHOULD always be in a "as near as possible ready for + release/production" state to reduce the friction of creating a new + release. +2. Changes + 1. Changes MUST be performed on a separate branch that SHOULD be referred to + as a "change branch". All change branches MUST have descriptive names. It + is RECOMMENDED that you commit often locally, and you SHOULD regularly + push your work to the same named branch on the remote server. + 2. When a change branch is created, the branch that it is created from + SHOULD be referred to as the "source branch". Each change branch also + needs a designated "merge target branch", typically this will be the same + as the source branch. + 3. Change branches MUST be regularly updated with any changes from their + source branch. This MUST be done by rebasing the change branch on top of + the source branch. To be clear you MUST NOT merge a source branch into a + change branch. + 4. After rebasing a change branch on top of its source branch you MUST push + the change branch to the remote server. This will require you do a force + push, and you SHOULD use the "--force-with-lease" git push option. + 5. To merge a change branch into its merge target branch, you MUST open a + "pull request" (or equivalent) so others can review and approve your + changes. + 6. A pull request MUST only be merged when the change branch is up-to-date + with its source branch, the test suite is passing, and you and others are + happy with the change. This is especially important if the merge target + is the master branch. + 7. To get feedback, help, or generally just discuss a change branch with + others, it is RECOMMENDED you do this by creating a pull request and + discuss the changes with others there. +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 + 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 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. + 2. 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" + 3. 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". + 4. 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. + 5. 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. 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 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. + 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 + 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. + +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/)