Update to reflect new branching policy

Author: hyperthunk

Diff for: wiki/contributing.md

@@ -18,6 +18,37 @@ we're saying here are just common sense and none of them is hard to follow.
 With this in mind, please try to observe the following guidelines when
 submitting patches.
 
+## Common Repository Format and Git Branches
+
+All Cloud Haskell repositories should conform to a common structure, with the
+exception of website and/or documentation projects. The structure is basically
+that of a cabal library or executable project, with a couple of additional files.
+
+```
+- project-name
+  - project-name.cabal
+  - Makefile
+  - LICENCE
+  - README.md
+  - src/
+  - tests/
+  - benchmarks/
+  - examples/
+  - regressions/
+```
+
+All repositories must use the same git branch structure: 
+
+* ongoing development takes place on the `master` branch
+* the code that goes into a release must be tagged as soon as it is uploaded to hackage
+* each release tag must then get its own release-x.y.z branch, branched from the tagged commit
+* after a release, the *release branch* is not merged back into `master`
+* patches can be submitted via branches off `master`, or from a `release-x.y.z` branch
+* features and bug-fixes that are compatible with `master` can be merged in directly
+* interim bug-fixes we **don't** want included (i.e., bug-fix only releases)
+  * are merged into a new release-x.y.z branch (taken from the prior release branch) instead
+  * these can, but do not have to be, merged into `master`
+
 ### __1. Check to see if your patch is likely to be accepted__
 
 We have a rather full backlog, so your help will be most welcome assisting
@@ -92,8 +123,8 @@ contain multitudinous compiler warnings will take longer to QA.
 Please be aware of whether or not your changes are actually a bugfix or a new
 feature, and branch from the right place accordingly. The general rule is:
 
-* new features must branch off `development`
-* bug fixes must branch off `master` (which is the stable, production branch)
+* new features should branch off `master`
+* bug fixes can branch off `master` or a `release-x.y.z` branch
 
 If you branch from the wrong place then you will be asked to rework your changes
 so try to get this right in the first place. If you're unsure whether a patch

Diff for: wiki/maintainers.md

@@ -6,31 +6,29 @@ wiki: Maintainers
 
 ### Maintainers
 
-This part of the guide is specifically for maintainers, and
-outlines the development process and in particular, the branching
-strategy. We also point out Cloud Haskell's various bits of
-infrastructure as they stand at the moment.
+This part of the guide is specifically for maintainers, and outlines the development
+process and in particular, the branching strategy. We also point out Cloud Haskell's
+various bits of infrastructure as they stand at the moment.
 
-Perhaps the most important thing to do as a maintainer, is to
-make other developers aware of what you're working on by assigning
-the Jira issue to yourself!
+Perhaps the most important thing to do as a maintainer, is to make other developers
+aware of what you're working on by assigning the Jira issue to yourself!
 
 ----
 #### Releases
 
 All releases are published to [hackage][3]. At some point we may start to
-make *nightly builds* available on this website.
+make *nightly builds* available on this website. We need some help setting that
+up though.
 
 ----
 
 #### Community
 
-We keep in touch through the [parallel-haskell google group][7],
-and once you've joined the group, by posting to the mailing list address:
-[email protected]. This is a group for **all** things related
-to concurrent and parallel Haskell. There is also a maintainer/developer
-centric [cloud-haskell-developers google group][9], which is more for
-in-depth questions about contributing to or maintaining Cloud Haskell.
+We keep in touch through the [parallel-haskell google group][7], and once you've
+joined the group, by posting to the mailing list address: [email protected].
+This is a group for **all** things related to concurrent and parallel Haskell. There is
+also a maintainer/developer centric [cloud-haskell-developers google group][9], which is
+more for in-depth questions about contributing to or maintaining Cloud Haskell.
 
 You might also find some of us hanging out at #haskell-distributed on
 freenode from time to time.
@@ -59,52 +57,66 @@ the timescales yet.
 
 ### Branching/Merging Policy
 
-The master branch is the **stable** branch, and should always be
-in a *releasable* state. This means that on the whole, only small
-self contained commits or topic branch merges should be applied
-to master, and tagged releases should always be made against it.
+The master branch is the *active development* branch. Small changes can be committed
+directly to `master`, or committed to a branche before getting merged. When we're
+ready to release, the project is tagged using the format `vX.Y.Z` once it has been
+published. Each release then gets its own `release-x.y.z` branch, created from the
+tagged commit. These can be used to produce interim/bug-fix releases if necessary.
 
-#### Tagging Releases
+A release tag should be of the form `x.y.z` and should **not** be prefixed with the
+repository name. Older tags use the latter form as they date from a time when all the
+Cloud Haskell source code lived under one git repository.
 
-A release tag should be of the form `x.y.z` and should **not**
-be prefixed with the repository name. Older tags use the latter
-form as they date from a time when all the Cloud Haskell source
-code lived under one git repository.
+Patches should be made against `master` **unless** they represent an interim bug-fix
+to a given `release-x-y-z` branch. The latter should be created against the branch
+they intend to fix.
 
 #### Development Branches
 
-Ongoing work can either be merged into master when complete or
-merged into development. Development is effectively an integration
-branch, to make sure ongoing changes and new features play nicely
-with one another. On the other hand, master is a 'stable' branch
-and therefore you should only merge into it if the result will be
-releasable.
-
-In general, we try to merge changes that belong to a major version
-upgrade into development, whereas changes that will go into the
-next minor version upgrade can be merged into master.
+Development should usually take place on a `feature-X` or `bugfix-Y` branch. The
+old `development` branch is defunct and will be removed at some point in the future.
+
+#### Interim and bug-fix only releases
+
+The complexity around *interim* releases is necessary to deal with situations where we
+need to patch a release, but `master` has already moved on, making the patch irrelevant
+for the next major release. For example, assuming a project is at version 1.2.3 and we
+find a bug in module `Foo.hs`. Users who're on v1.2.3 will want the fix asap for any
+production deployments, yet `Foo.hs` has been completely re-written/replaced on `master`
+and the bugfix isn't needed there. To support user's who do not wish to wait for v2.0.0
+to be released, we create a `release-1.2.4` branch and merge the bugfix into that, but
+we do **not** merge this back into master, since the patch won't apply.
+This way, subsequent bug fixes to the 1.2.x series can also continue in parallel with
+changes to `master` if necessary.
+
+What happens if we have a patch for `release-1.2.3` that *is* applicable to master, but
+won't apply cleanly due to changes since the release was tagged? In this situation, we
+create a bug-fix release branch as usual, into which the patch is merged. A maintainer
+will then have to retro-fit the patch so that it can be applied to `master`. This is
+a somewhat ugly, since if we wish to create subsequent bug-fixes and create another
+1.2.5 branch (viz the example above), we'll may have to manually transplant some changes
+from `master` in the process.
 
 #### Keeping History
 
-Try to make only clean commits, so that bisect will continue to work.
-At the same time, it's best to avoid making destructive updates. If
-you're planning on doing lots of squashing, then work in a branch
-and don't commit directly to development - and **definitely** not to
-master.
+Try to make only clean commits, so that bisect will continue to work. At the same time,
+it can be helpful to avoid making destructive updates. If you're planning on doing lots
+of squashes, then work in a branch and don't commit directly to `master` until you're
+finished and ready to QA and merge.
 
 #### Committing without triggering CI builds
 
-Whilst we're on travis-ci, you can do this by putting the text
-`[ci skip]` anywhere in the commit message. Please, please
-**do not** put this on the first line of the commit message.
+Whilst we're on travis-ci, you can do this by putting the text `[ci skip]` anywhere in
+the commit message. Please, please **do not** put this on the first line of the commit
+message.
 
 Once we migrate to Bamboo, this may change.
 
 #### Changing Jira bugs/issues via commit messages
 
-You can make complex changes to one or more Jira issues with a single
-commit message. As with skipping CI builds, please **do not** put this
-messy text into the first line of your commit messages.
+You can make complex changes to one or more Jira issues with a single commit message.
+As with skipping CI builds, please **do not** put this messy text into the first line
+of your commit messages.
 
 Details of the format/syntax required to do this can be found on
 [this Jira documentation page](https://confluence.atlassian.com/display/AOD/Processing+JIRA+issues+with+commit+messages)
@@ -125,11 +137,10 @@ See https://cloud-haskell.atlassian.net/browse/INFRA-1 for details.
 
 ### Release Process
 
-First of all, a few prior warnings. **Do not** tag any projects
-until *after* you've finished the release. If you build and tag
-three projects, only to find that a subsequent dependent package
-needs a bit of last minute surgery, you'll be sorry you didn't
-wait. With that in mind....
+First of all, a few prior warnings. **Do not** tag any projects until *after*
+you've finished and uploaded the release. If you build and tag three projects,
+only to find that a subsequent dependent package needs a bit of last minute
+surgery, you'll be sorry you didn't wait. With that in mind....
 
 Before releasing any source code, make sure that all the jira tickets
 added to the release are either resolved or remove them from the
@@ -156,11 +167,13 @@ too!
 
 **Now** you should tag all the projects with the relevant version number.
 Since moving to individual git repositories, the tagging scheme is now
-`x.y.z` and *not* `<project>-x.y.z`.
+`x.y.z` and *not* `<project>-x.y.z`. Once you've tagged the release, create
+a branch named `release-x.y.z` and push both the newly created tag(s) and the
+branch(es).
 
 Once the release is out, you should go to [JIRA](https://cloud-haskell.atlassian.net)
-and close all the tickets for the release. Jira has a nice 'bulk change'
-feature that makes this very easy.
+and close all the tickets for the release. Jira has a nice 'bulk change' feature
+that makes this very easy.
 
 After that, it's time to tweet about the release, post to the parallel-haskell
 mailing list, blog etc. Spread the word.