Merge pull request #5 from jimeh/add-faq-section

Add FAQ Section

common-flow.md

@@ -235,6 +235,90 @@ 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
+---
+
+### 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 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.
+- 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.
+
+### 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 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
+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.
+
+### 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:
+
+- 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.
+
+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 more time on your hands.
+
 About
 -----