[#4617] Add information about versioning external test data. (#74)

docs/office/onboarding.rst

@@ -86,22 +86,22 @@ Ask the tech lead for any questions.
 * Take note of the `coding conventions <http://geck.chevah.com/>`_ applied for this project. These general coding conventions are for all 'texts' (code, documentation, etc). 
 
 * There are specific rules that apply to programming languages.
-  Begin by reading the general `coding conventions <http://geck.chevah.com/en/latest/styleguide/index.html>`_.
+  Begin by reading the general `styleguide <http://geck.chevah.com/en/latest/styleguide/index.html>`_.
   Then review each language specific convention as you will be writing in that language.
 
 * While you are in IRC on #chevah "in the office", set to auto-away to let others know that you are not at the computer.
-Set the away status to "busy" (/away busy) if you are working at something and don't want to be disturbed.
+  Set the away status to "busy" (/away busy) if you are working at something and don't want to be disturbed.
 
 * You will use your own hardware for work tasks.
   To compensate for this usage of your hardware we will cover hardware expenses for your home computer.
   If you need a hardware component or peripheral that will help your work related tasks, ask and we can cover those expenses.
   Ask tech lead for details.
 
 * Each task that you are working on should have a ticket in Trac/Github.
-If there is no ticket, create one and start the `Ticket Work Flow <http://geck.chevah.com/en/latest/product/tickets.html>`_. 
+  If there is no ticket, create one and start the `Ticket Work Flow <http://geck.chevah.com/en/latest/product/tickets.html>`_. 
 
 * While some tasks are on Github, there is a Trac/Github integration.
-See `Overview of the GitHub and Trac integration <http://geck.chevah.com/en/latest/programming/review.html>`_.
+  See `Overview of the GitHub and Trac integration <http://geck.chevah.com/en/latest/programming/review.html>`_.
 
 * Tickets corresponding to you that you are currently working should have the 'owner' value set to your Trac username.
 
@@ -114,7 +114,7 @@ See `Overview of the GitHub and Trac integration <http://geck.chevah.com/en/late
 * When starting a support ticket, request the OS version architecture used and version of the products.
 
 * Before a Pull Request is closed, it must be approved by at least one other team member.
-Further info of the `Review process <http://geck.chevah.com/en/latest/programming/review.html>`_.
+  Further info of the `Review process <http://geck.chevah.com/en/latest/programming/review.html>`_.
 
 * Leave days can be requested at any time.
   Check the dedicated page in Trac.

docs/programming/review.rst

@@ -214,7 +214,7 @@ PR title as the commit message with the PR ID appended to it.
 
 If the PR title is `[#1234] What was done in this branch` the commit message
 will be `[#1234] What was done in this branch. (#4567)`
-Where 1234 is the Trac ticket id and 4567 is the GitHub PR id::
+Where 1234 is the Trac ticket id and 4567 is the GitHub PR id.
 
 When doing manual merge using git, use squash merge and don't use the
 default commit message.

docs/programming/testing.rst

@@ -99,17 +99,26 @@ same versioning system as the test code.
 In some exceptional cases (chicken and egg problems) there is no option to
 generate the data at test time or to keep in the same versioning system as
 the test code.
-For example when you want to run and end to end test to check that you can
+
+For example when you want to run an end to end test to check that you can
 read and write a document from a database, you will have to start with testing
 the read operation against an existing data.
 
-In this case make sure that all pre-generated data is versioned using a well
-defined convention and that the pre-generated data is never modified or
-removed.
-In this way you can still run older versions of the code.
-Pre-generated data include pre-generated access to the outside resource
-(username / password / server address / port)
+All testing data that is controlled outside of the tests for which is not
+directly generated by the test should be immutable.
+Once a branch using the external data is merged into master, the external data
+should never be changed.
+
+This includes pre-generated access to the outside resource (username /
+password / server address / port). For this sort of persistent configuration
+make sure to use a prefix like `ci-`, making it explict that the resource is
+used for automated tests.
 
+In the same way the version for the resource should be added as a suffix,
+like `-v1`.
+For example a username used by automated tests could be `ci-testuser-v1`.
+
+In this way you can still run older versions of the code.
 
 Types of tests
 ==============
@@ -969,4 +978,4 @@ Here are the pages I used to create this page.
  * http://stackoverflow.com/q/67299/539264
  * http://blog.brianbutton.io/index.php/2005/08/14/i-really-did-mean-it-avoid-setup-and-teardown/
  * http://webcache.googleusercontent.com/search?q=cache:OsTWl-j736kJ:agilesoftwaredevelopment.com/blog/vaibhav/acceptance-testing-what-why-how+&cd=1&hl=en&ct=clnk&gl=ie (cached)
-* https://testing.googleblog.com/2016/05/flaky-tests-at-google-and-how-we.html
+ * https://testing.googleblog.com/2016/05/flaky-tests-at-google-and-how-we.html