Clarify the stable/development/experimental workflow in contribution …

…guide

contribution.md

@@ -59,6 +59,9 @@ Please do! All of the code in `x-dash` is peer-reviewed by members of The App an
   - ### Discuss features first
     If you're thinking of opening a pull request that adds a feature, you'll save yourself some time and effort if you [discuss it in a feature request first](#requesting-features). The review is guaranteed to go more smoothly if we've chatted about it beforehand.
 
+  - ### Check the workflow and release guidelines
+    The project follows a scheduled release workflow so we encourage the separation of stable, development, and experimental code. See the [Git workflow](#git-workflow) and the [release guidelines](release-guidelines.md) for more information.
+
   - ### Update the documentation
     The user documentation should be kept up to date with any changes made. Use inline code comments as developer documentation, focusing more on _why_ your code does something than _what_ it's doing.
 
@@ -78,6 +81,17 @@ Please do! All of the code in `x-dash` is peer-reviewed by members of The App an
     When fixing a bug, reference the original report; when adding a feature, link to the original feature request. It'll help us massively!
 
 
+## Git workflow
+
+This project follows a workflow designed around project releases. It is less strict than [Gitflow] but we encourage the separation of stable, development, and experimental branches in order to follow a scheduled release cycle.
+
+- The `master` branch is for the current stable release. Bugfixes are merged into this branch.
+- The `development` branch is for upcoming major or minor releases. This branch tracks `master` and new features are merged into it.
+- Branches for new features should track and raise pull requests against the `development` branch or `master` branch if there are not any upcoming releases planned.
+
+[Gitflow]: https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow
+
+
 ## Code style
 
 The best way to ensure you stick to the x-dash code style is to make your work consistent with the code around it. We also provide a [Prettier] configuration to automatically format files and run [ESLint] before any tests so don't let it get in the way of your flow – you can fix it afterwards!
@@ -118,7 +132,8 @@ The best way to ensure you stick to the x-dash code style is to make your work c
 
 ## Testing
 
-We use [Jest] for testing `x-dash` components and packages. Most commonly this takes the form of snapshots generated from the stories associated with a component. We enforce code quality with [ESLint].
+We use [Jest] for testing `x-dash` components and packages. Most commonly this takes the form of snapshots generated from the stories associated with a component. We enforce code quality with [ESLint]. To learn more about testing components see the [testing components documentation].
 
 [Jest]: https://jestjs.io/
 [ESLint]: https://eslint.org/
+[testing components documentation]: https://financial-times.github.io/x-dash/docs/components/testing

release-guidelines.md

@@ -1,21 +1,10 @@
 # Release Guidelines
 
-## Branching and Git strategy
-
-This project follows a workflow designed around project releases. It is less strict than [Gitflow] but we encourage the separation of stable, development, and experimental branches in order to follow a scheduled release cycle.
-
-- The `master` branch is for the current stable release. Bugfixes are merged into this branch.
-- The `development` branch is for upcoming major or minor releases. This branch tracks `master` and new features are merged into it.
-- Branches for new features should track and raise pull requests against the `development` branch or `master` branch if there are not any upcoming releases planned.
-
-[Gitflow]: https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow
-
-
 ## Experimental features
 
-Only stable, well tested components and packages may be present in the master or development branches. _Any publishable code in either master or latest development branch should have been tested in both The App and FT.com_. This is so we do not release unproven components with a stable version number.
+Only stable, well tested components and packages may be present in the master or development branches. _Any publishable code in the master or development branches must have been tested in both The App and FT.com_. This is so we do not release unproven components with a stable version number.
 
-To develop your component create a new feature branch including your module name, for example if you are building a new tabs component you would create a branch named `feature-x-tabs`. Your component will stay in this branch until it is ready to be merged into the next major or minor release so you are encouraged to merge from the master branch regularly. You are welcome to raise pull requests against your feature branch if you need to.
+To develop your component create a new feature branch including your module name, for example if you are building a new tabs component you would create a branch named `feature-x-tabs`. Your component will stay in this branch until it is ready to be merged into the next major or minor release so you are encouraged to merge from or rebase onto the latest development or master branch regularly. You are welcome to raise pull requests against your feature branch if you need to.
 
 Because experimental modules will not be included in any stable releases we allow them to be published separately using a pre-1.0.0 version number. You are free to make as many prereleases as you need. To create a prerelease of your experimental module you must create a tag in the format `module-name-v0.x.x`, for example to release the tabs component you would create tag named `x-tabs-v0.0.1` for the latest commit in the `feature-x-tabs` branch.