Update to version 1.0.0-rc.5

index.md

@@ -1,25 +1,39 @@
 ---
-title: Git Common-Flow 1.0.0-rc.4
-version: 1.0.0-rc.4
+title: Git Common-Flow 1.0.0-rc.5
+version: 1.0.0-rc.5
 ---
-Git Common-Flow 1.0.0-rc.4
+Git Common-Flow 1.0.0-rc.5
 ===========================
 
-<img src="/spec/1.0.0-rc.4.svg" width="100%" />
+<img src="/spec/1.0.0-rc.5.svg" width="100%" />
 
-Summary
--------
+Introduction
+------------
 
 Common-Flow is an attempt to gather a sensible selection of the most common
 usage patterns of git into a single and concise specification. It is based on
 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.
+into account how a lot of open source projects most commonly use git.
 
 In short, Common-Flow is essentially GitHub Flow with the addition of versioned
 releases, optional release branches, and without the requirement to deploy to
 production all the time.
 
+Summary
+-------
+
+- The "master" branch is the mainline branch with latest changes, and must not
+  be broken.
+- Changes (features, bugfixes, etc.) are done on "change branches" created from
+  the master branch.
+- Rebase change branches [early and often](https://i.imgur.com/1RS8x2d.png).
+- When a change branch is stable and ready, it is merged back in to master.
+- A release is just a git tag who's name is the exact release version string
+  (e.g. "2.11.4").
+- Release branches can be used to avoid change freezes on master. They are not
+  required, instead they are available if you need them.
+
 Terminology
 -----------
 
@@ -48,7 +62,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
 interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
 
 1. TL;DR
-    1. Don't break the master branch.
+    1. Do not break the master branch.
     2. A release is a git tag.
 2. The Master Branch
     1. A branch named "master" MUST exist and it MUST be referred to as the
@@ -108,8 +122,9 @@ interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
        happy with the change. This is especially important if the merge target
        is the master branch.
     5. To get feedback, help, or generally just discuss a change branch with
-       others, the RECOMMENDED way to do so is by creating a pull request and
-       discuss the changes with others there.
+       others, it is RECOMMENDED you create a pull request and discuss the
+       changes with others there. This leaves a clear and visible history of
+       how, when, and why the code looks and behaves the way it does.
 5. Versioning
     1. A "version string" is a typically mostly numeric string that identifies a
        specific version of a project. The version string itself MUST NOT have a
@@ -197,8 +212,8 @@ interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
        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".
+       "release-2.9" from the "2.9.7" release tag. The security fix release will
+       then end up being version "2.9.8".
     5. To create a new release from a long-term release branch, you MUST follow
        the same process as a release from the master branch, except the
        long-term release branch takes the place of the master branch.
@@ -252,7 +267,7 @@ really change much:
 
 - You create change branches instead of feature branches, without the need of a
   "feature/" or "change/" prefix in the branch name.
-- Change branches are typically created off of and merged back into "master"
+- Change branches are typically created from and merged back into "master"
   instead of "develop".
 - Creating a release is done by simply creating a git tag, typically on the
   master branch.
@@ -301,12 +316,18 @@ is and what it does. Here's a few examples:
 - remove-sort-by-middle-name-functionality
 - update-font-awesome
 - change-search-behavior
+- improve-pagination-performance
 - tweak-footer-style
 
 Notice how none of these have any prefixes like "feature/" or "hotfix/", they're
 not needed when branch names are properly descriptive. However there's nothing
-to say you can't use such prefixes if you want. That also means that you can add
-ticket number prefixes if your team/org has that as part of it's process.
+to say you can't use such prefixes if you want.
+
+You can also add ticket numbers to the branch name if your team/org has that as
+part of it's process. But it is recommended that ticket numbers are added to the
+end of the branch name. The ticket number is essentially metadata, so put it at
+the end and out of the way of humans trying to read the descriptive name from
+left to right.
 
 ### How do we release an emergency hotfix when the master branch is broken?
 
@@ -329,7 +350,7 @@ About
 -----
 
 The Git Common-Flow specification is authored
-by [Jim Myhrberg](http://jimeh.me).
+by [Jim Myhrberg](https://jimeh.me/).
 
 If you'd like to leave feedback,
 please [open an issue on GitHub](https://github.com/jimeh/common-flow/issues).
@@ -337,5 +358,5 @@ 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/)
+[Creative Commons - CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)