Describe refdata update and workflow refactor (#861)

* add update refdata description

* update the workflow orders and toctree

docs/workflow/development_workflow.rst

@@ -8,39 +8,13 @@ workflow is taken from `Astropy <http://docs.astropy.org
 /en/stable/development/workflow/development_workflow.html>`_ and credit belongs
 to the Astropy team for designing it.
 
-Preparation and Working with Git
-================================
-
-The first step is to setup up a python environment. We recommend to use
-Anaconda for this purpose and refer to our :doc:`Installation guide
-<../installation>` which covers this topic. Once the python environment is
-running consult :doc:`git_workflow` to learn about interacting with git and
-github for the purpose of developing TARDIS.
-
-
-General Workflow to add a new feature
-=====================================
-
-In TARDIS we aim to stick to a test driven development. This uses the testing
-framework extensively starting with a test that shows this feature lacking via
-the implementation of the feature until the merging of the code to the main
-repository.
-
-In most cases we try to break down big features into small, quantifiable goals
-which are then acted upon.
-
-* Document feature to be added in an issue and maybe ask the mailing
-  list if this feature exists
-* Write a test that demonstrates what feature will be added.
-* Run the test to verify that it fails in the way you think it should.
-* If it fails in an unexpected way, your test may be wrong. This is a
-  great time to ask the group for guidance
-* If it passes, you are done! You just added test coverage to an
-  already existing feature, and that is great! (unlikely)
-* Add the feature (also known as "a simple matter of programming").
-* Run the test to verify that it passes.
-* Write documentation about your feature.
-* close issue/partial PR and add to changelog.
-
-
-.. include:: release_workflow.rst
+
+
+
+.. toctree::
+
+    git_workflow
+    release_workflow
+    update_refdata
+
+

docs/workflow/git_workflow.rst

@@ -1,15 +1,40 @@
 .. _development-workflow:
 
-=======================
-Workflow for Developers
-=======================
+General Workflow to add a new feature
+=====================================
 
-In this document, we refer to the Tardis ``master`` branch as the *trunk*.
+In TARDIS we aim to stick to a test driven development. This uses the testing
+framework extensively starting with a test that shows this feature lacking via
+the implementation of the feature until the merging of the code to the main
+repository.
+
+In most cases we try to break down big features into small, quantifiable goals
+which are then acted upon.
+
+* Document feature to be added in an issue and maybe ask the mailing
+  list if this feature exists
+* Write a test that demonstrates what feature will be added.
+* Run the test to verify that it fails in the way you think it should.
+* If it fails in an unexpected way, your test may be wrong. This is a
+  great time to ask the group for guidance
+* If it passes, you are done! You just added test coverage to an
+  already existing feature, and that is great! (unlikely)
+* Add the feature (also known as "a simple matter of programming").
+* Run the test to verify that it passes.
+* Write documentation about your feature.
+* close issue/partial PR and add to changelog.
+
+
+Preparation and Working with Git
+================================
+
+In this document, we refer to the Tardis ``master`` branch as the *trunk*. The first step is to setup up a python environment. We recommend to use
+Anaconda for this purpose and refer to our :doc:`Installation guide <../installation>` which covers this topic.
 
 .. _forking:
 
 Creating a fork
-===============
+---------------
 
 You need to do this only once for each package you want to contribute to. The
 instructions here are very similar to the instructions at
@@ -110,7 +135,7 @@ In detail
    Your fork is now set up correctly, and you are ready to hack away.
 
 Installing TARDIS in develop mode
-==================================
+---------------------------------
 
 TARDIS is designed so that it can generally be used directly out of the source
 tree by using ``import `` when running Python in the source of an
@@ -127,7 +152,7 @@ TARDIS repository clone.
    interpreter and ``import tardis``.
 
 Workflow summary
-================
+----------------
 
 This section gives a summary of the workflow to follow once you have
 successfully forked the repository. The details for each of these steps are
@@ -174,15 +199,15 @@ see what you've done, and why you did it.
 See `linux git workflow`_ and `ipython git workflow`_ for some explanation.
 
 Deleting your master branch
-===========================
+---------------------------
 
 It may sound strange, but deleting your own ``master`` branch can help reduce
 confusion about which branch you are on.
 
 .. _update-mirror-trunk:
 
 Updating the mirror of trunk
-============================
+----------------------------
 
 From time to time you should fetch the upstream (trunk) changes from GitHub::
 
@@ -196,7 +221,7 @@ you last checked, ``upstream/master`` will change after you do the fetch.
 .. _make-feature-branch:
 
 Making a new feature branch
-===========================
+---------------------------
 
 When you are ready to make some changes to the code, you should start a new
 branch. Branches that are for a collection of related edits are often called
@@ -237,10 +262,10 @@ From now on git will know that ``my-new-feature`` is related to the
 .. _edit-flow:
 
 The editing workflow
-====================
+--------------------
 
 Overview
---------
+^^^^^^^^
 
 Make changes, test, and::
 
@@ -249,7 +274,7 @@ Make changes, test, and::
    git push
 
 In more detail
---------------
+^^^^^^^^^^^^^^
 
 #. Make some changes
 
@@ -307,7 +332,7 @@ In more detail
    `git push`_).
 
 Asking for your changes to be reviewed and/or merged
-====================================================
+----------------------------------------------------
 
 When you are ready to ask for someone to review your code and consider a merge:
 
@@ -335,7 +360,7 @@ When you are ready to ask for someone to review your code and consider a merge:
 .. _using-virtualenv:
 
 Making sure your Pull request stays up-to-date
-==============================================
+----------------------------------------------
 
 More often then not it will take a few days until a Pull Request is
 merged as the community gives feedback and/or you add new fixes. During this
@@ -345,7 +370,7 @@ To make sure that your changes are still working on the new master you want to
 
 
 Rebasing on trunk
------------------
+^^^^^^^^^^^^^^^^^
 
 Let's say you thought of some work you'd like to do. You
 :ref:`update-mirror-trunk` and :ref:`make-feature-branch` called
@@ -423,7 +448,7 @@ this would re-write commit history and thus cause problems for all others.
 .. _recovering-from-mess-up:
 
 Recovering from mess-ups
-------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 Sometimes, you mess up merges or rebases. Luckily, in git it is relatively
 straightforward to recover from such mistakes.
@@ -452,7 +477,7 @@ If you forgot to make a backup branch::
 
 
 Reviewing and helping others with Pull Requests
-===============================================
+-----------------------------------------------
 
 Github offers an extensive array of tools to comment on Pull Requests (line
 based, normal forum-like discussion, etc.). This system is described here in

docs/workflow/update_refdata.rst

@@ -0,0 +1,37 @@
+**************************************
+Procedure to update the reference data
+**************************************
+
+We asume that you have added the necessary changes to TARDIS and have a
+PR open.
+
+#. clone tardis-refdata (`git clone tardis-refdata`; you need to have git lfs installed) then make a new branch named
+    the same as your new tardis feature branch.
+#. Generate new reference data (in your tardis directory and right branch) offline using
+    `python setup.py test --args="--tardis-refdata=<path to refdata repo/with the right branch> --generate-reference"`
+#. Rerun the tests and see if it does not fail using
+    `python setup.py test --args="--tardis-refdata=<path to refdata repo/with the right branch>"`
+#. Switch to tardis-refdata. Commit the changed ref-data and open a PR on tardis-refdata
+#. Make a copy of the refdata comparer notebook provided in TARDIS-refdata to check if there are
+    any unexpected changes in the updated reference data and the previous reference data
+#. Switch back to the TARDIS directory. Open `.travis.yml`
+
+#. Change the following lines
+
+    .. code-block:: None
+
+        - if [[ $TEST_MODE == 'spectrum' ]]; then git fetch origin pull/<your TARDIS-refdata PR number; not the TARDIS PR number>/head:<some descriptive name>; fi
+        - if [[ $TEST_MODE == 'spectrum' ]]; then git checkout <some descriptive name>; fi```
+
+#. Commit the `.travis.yml` to your Pull request
+#. Make sure that your TARDIS PR now passes on TRAVIS.
+#. Then merge the PR on tardis-refdata.
+#. Then change `.travis.yml` to
+
+    .. code-block:: None
+
+        - if [[ $TEST_MODE == 'spectrum' ]]; then git fetch origin; fi
+        - if [[ $TEST_MODE == 'spectrum' ]]; then git checkout origin/master; fi```
+#. Then make sure that your TARDIS PR passes again.
+#. Then merge your PR to TARDIS master
+#. Congratulations - you updated TARDIS to be better. Have a beer and steak (or Tofu if you are vegetarian/vegan)