From f7170875d042e322224198954f60c9309bcdd199 Mon Sep 17 00:00:00 2001 From: Jim Myhrberg Date: Mon, 17 Jul 2017 23:37:08 +0100 Subject: [PATCH 01/10] Start work on FAQ section --- common-flow.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/common-flow.md b/common-flow.md index 069bba8..62b866b 100644 --- a/common-flow.md +++ b/common-flow.md @@ -235,6 +235,18 @@ interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). and creates a merge commit to mark the integration of the branch with master. +FAQ +--- + +**What does "descriptive name" mean in terms of change branches?** + +[answer goes here] + +**What if there's a emergency hotfix that needs to be released, but for whatever +reason, master has changes that cannot be released right now?** + +[answer goes here] + About ----- From 34cb2c20e0adf03e521a1488f9e9292699b000cf Mon Sep 17 00:00:00 2001 From: Jim Myhrberg Date: Sat, 26 Aug 2017 20:53:19 +0100 Subject: [PATCH 02/10] Add Git Flow question --- common-flow.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/common-flow.md b/common-flow.md index 62b866b..956ff46 100644 --- a/common-flow.md +++ b/common-flow.md @@ -238,6 +238,10 @@ interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). FAQ --- +**Why use Common-Flow instead of Git Flow, and how do they differ?** + +[answer goes here] + **What does "descriptive name" mean in terms of change branches?** [answer goes here] From 927a00a7bdd734077ef9db87671bda0d8652bb6f Mon Sep 17 00:00:00 2001 From: Jim Myhrberg Date: Sat, 26 Aug 2017 23:19:16 +0100 Subject: [PATCH 03/10] Add answer to Common-Flow vs Git Flow FAQ question --- common-flow.md | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/common-flow.md b/common-flow.md index 956ff46..410537f 100644 --- a/common-flow.md +++ b/common-flow.md @@ -238,9 +238,35 @@ interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). FAQ --- -**Why use Common-Flow instead of Git Flow, and how do they differ?** +**Why use Common-Flow instead of Git Flow, and how does it differ?** -[answer goes here] +Common-Flow tries to be a lot less complicated than Git Flow by having fewer +types of branches, and simpler rules. Normal day to development doesn't 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" + instead of "develop". +- Creating a release is done by simply creating a git tag, typically on the + master branch. + +In detail, the main differences between Git Flow and Common-Flow are: + +- There is no "develop" branch, there is only a "master" branch which contains + the latest work. In Git Flow the master branch effectively ends up just being + a pointer to the latest release, despite the fact that Git Flow includes + release tags too. In Common-Flow you just look at the tags to find the latest + release. +- There are no "feature" or "hotfix" branches, there's only "change" + branches. Any branch that is not master and introduces changes is a change + branch. Change branches also don't have a enforced naming convention, they + just have to have a "descriptive name". This makes things simpler and allows + more flexibility. +- Release branches are available, but optional. Instead of enforcing the use of + release branches like Git Flow, Common-Flow only recommends the use of release + branches when it makes things easier. If creating a new release by tagging + "master" works for you, great, do that. **What does "descriptive name" mean in terms of change branches?** From 68e0502dacb8cc8d24e8373c02cd3bf070b0c555 Mon Sep 17 00:00:00 2001 From: Jim Myhrberg Date: Sat, 26 Aug 2017 23:19:54 +0100 Subject: [PATCH 04/10] Add Common-Flow vs GitHub Flow FAQ question --- common-flow.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/common-flow.md b/common-flow.md index 410537f..4fd427e 100644 --- a/common-flow.md +++ b/common-flow.md @@ -268,6 +268,22 @@ In detail, the main differences between Git Flow and Common-Flow are: branches when it makes things easier. If creating a new release by tagging "master" works for you, great, do that. +**Why use Common-Flow instead of GitHub Flow, and how does it differ?** + +Common-Flow is essentially GitHub Flow with the addition of a "Release" concept +that uses tags. It also attempts to define how certain common tasks are done, +like updating change/feature branches from their source branches for +example. This is to help end arguments about how such things are done. + +If a deployment/release for you is just getting the latest code in the master +branch out, without caring about bumping version numbers or anything, then +GitHub Flow is a good fit for you, and you probably don't need the extras of +Common-Flow. + +However if your deployments/releases have specific version numbers, then +Common-Flow gives you a simple set of rules of how to create and manage +releases, on top of what GitHub Flow already does. + **What does "descriptive name" mean in terms of change branches?** [answer goes here] From 77332f5f9ad9c7b6f3d038d60b3ca5fcd5e7f140 Mon Sep 17 00:00:00 2001 From: Jim Myhrberg Date: Sat, 26 Aug 2017 23:20:34 +0100 Subject: [PATCH 05/10] Add answer to "what does describe name mean?" FAQ question --- common-flow.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/common-flow.md b/common-flow.md index 4fd427e..dc59a85 100644 --- a/common-flow.md +++ b/common-flow.md @@ -286,7 +286,21 @@ releases, on top of what GitHub Flow already does. **What does "descriptive name" mean in terms of change branches?** -[answer goes here] +It means what it sounds like. The name should be descriptive, as in by just +reading the name of the branch you should understand what the branch's purpose +is and what it does. Here's a few examples: + +- add-2fa-support +- fix-login-issue +- remove-sort-by-middle-name-functionality +- update-font-awesome +- change-search-behavior +- 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. **What if there's a emergency hotfix that needs to be released, but for whatever reason, master has changes that cannot be released right now?** From 6735136a5da1ddae28762fcb91b1f9838adfcc39 Mon Sep 17 00:00:00 2001 From: Jim Myhrberg Date: Sat, 26 Aug 2017 23:25:49 +0100 Subject: [PATCH 06/10] Add answer to hotfix with broken master FAQ question --- common-flow.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/common-flow.md b/common-flow.md index dc59a85..3b7200e 100644 --- a/common-flow.md +++ b/common-flow.md @@ -303,9 +303,22 @@ 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. **What if there's a emergency hotfix that needs to be released, but for whatever -reason, master has changes that cannot be released right now?** +reason, the master branch has changes that cannot be released right now?** -[answer goes here] +This should ideally never happen, as it most likely means the master branch is +broken. However if it does happen, you can do one of the following: + +- Review why the master branch can't be deployed, and revert the changes that + are preventing a release. Then apply the hotfix and release. +- Or use a short-term release branch created from the latest release tag instead + of the master branch. Apply the hotfix to the release branch, create a release + tag on the release branch, and then merge it back into master. + +In this situation, it is recommended you try to revert the offending changes +that's preventing a new release from master. But if that proves to be a +complicated task and you're short on time, a short-term release branch gives you +a instant fix to the situation at hand, and let's you resolve the issues with +the master branch when you have time. About ----- From d3e6630e2ec50853cee3ca4dde56e20632a24e92 Mon Sep 17 00:00:00 2001 From: Jim Myhrberg Date: Sat, 26 Aug 2017 23:51:24 +0100 Subject: [PATCH 07/10] Improve style of FAQ section --- common-flow.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/common-flow.md b/common-flow.md index 3b7200e..c9cba43 100644 --- a/common-flow.md +++ b/common-flow.md @@ -238,7 +238,7 @@ interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). FAQ --- -**Why use Common-Flow instead of Git Flow, and how does it differ?** +### Why use Common-Flow instead of Git Flow, and how does it differ? Common-Flow tries to be a lot less complicated than Git Flow by having fewer types of branches, and simpler rules. Normal day to development doesn't really @@ -268,7 +268,7 @@ In detail, the main differences between Git Flow and Common-Flow are: branches when it makes things easier. If creating a new release by tagging "master" works for you, great, do that. -**Why use Common-Flow instead of GitHub Flow, and how does it differ?** +### Why use Common-Flow instead of GitHub Flow, and how does it differ? Common-Flow is essentially GitHub Flow with the addition of a "Release" concept that uses tags. It also attempts to define how certain common tasks are done, @@ -284,7 +284,7 @@ However if your deployments/releases have specific version numbers, then Common-Flow gives you a simple set of rules of how to create and manage releases, on top of what GitHub Flow already does. -**What does "descriptive name" mean in terms of change branches?** +### What does "descriptive name" mean in terms of change branches? It means what it sounds like. The name should be descriptive, as in by just reading the name of the branch you should understand what the branch's purpose @@ -302,14 +302,13 @@ 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. -**What if there's a emergency hotfix that needs to be released, but for whatever -reason, the master branch has changes that cannot be released right now?** +### How do we release an emergency hotfix when the master branch is broken?** -This should ideally never happen, as it most likely means the master branch is -broken. However if it does happen, you can do one of the following: +This should ideally never happen, however if it does you can do one of the +following: -- Review why the master branch can't be deployed, and revert the changes that - are preventing a release. Then apply the hotfix and release. +- Review why the master branch is broken and revert the changes that caused the + issues. Then apply the hotfix and release. - Or use a short-term release branch created from the latest release tag instead of the master branch. Apply the hotfix to the release branch, create a release tag on the release branch, and then merge it back into master. @@ -318,7 +317,7 @@ In this situation, it is recommended you try to revert the offending changes that's preventing a new release from master. But if that proves to be a complicated task and you're short on time, a short-term release branch gives you a instant fix to the situation at hand, and let's you resolve the issues with -the master branch when you have time. +the master branch when you have more time on your hands. About ----- From f4da2744680827e84e53824c146dcc90e4a21203 Mon Sep 17 00:00:00 2001 From: Jim Myhrberg Date: Sat, 26 Aug 2017 23:55:32 +0100 Subject: [PATCH 08/10] Fix typo --- common-flow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common-flow.md b/common-flow.md index c9cba43..73fa29d 100644 --- a/common-flow.md +++ b/common-flow.md @@ -302,7 +302,7 @@ 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. -### How do we release an emergency hotfix when the master branch is broken?** +### How do we release an emergency hotfix when the master branch is broken? This should ideally never happen, however if it does you can do one of the following: From 741dda313e52ea4ef6795615871f6813fba68363 Mon Sep 17 00:00:00 2001 From: Jim Myhrberg Date: Sat, 26 Aug 2017 23:55:46 +0100 Subject: [PATCH 09/10] Improve grammar of descriptive name FAQ question --- common-flow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common-flow.md b/common-flow.md index 73fa29d..d104aab 100644 --- a/common-flow.md +++ b/common-flow.md @@ -284,7 +284,7 @@ However if your deployments/releases have specific version numbers, then Common-Flow gives you a simple set of rules of how to create and manage releases, on top of what GitHub Flow already does. -### What does "descriptive name" mean in terms of change branches? +### What does "descriptive name" mean for change branches? It means what it sounds like. The name should be descriptive, as in by just reading the name of the branch you should understand what the branch's purpose From 5f9513df4d2f75f8a31f7137ba9bc6e1024007c3 Mon Sep 17 00:00:00 2001 From: Jim Myhrberg Date: Sun, 27 Aug 2017 00:17:38 +0100 Subject: [PATCH 10/10] Fix typo --- common-flow.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/common-flow.md b/common-flow.md index d104aab..0e8a508 100644 --- a/common-flow.md +++ b/common-flow.md @@ -241,8 +241,8 @@ FAQ ### Why use Common-Flow instead of Git Flow, and how does it differ? Common-Flow tries to be a lot less complicated than Git Flow by having fewer -types of branches, and simpler rules. Normal day to development doesn't really -change much: +types of branches, and simpler rules. Normal day to day development doesn't +really change much: - You create change branches instead of feature branches, without the need of a "feature/" or "change/" prefix in the branch name.