instructions to add/replace data files (#17)

* instructions to add/replace data files
* add release notes
* rename the release notes file
---------

Signed-off-by: Jose Borreguero <[email protected]>

Author: jmborr

docs/index.rst

@@ -11,7 +11,7 @@ User Guide
 
    /source/user/conda_environments
    /source/user/reduce
-   /source/releases
+   /source/release_notes
 
 Contacting the Team
 +++++++++++++++++++

docs/source/developer/developer.rst

@@ -55,6 +55,10 @@ synchronized across these files:
 
 Using the Data Repository usansred-data
 ---------------------------------------
+Below follows a simplified rendering of the more detailed instructions on
+`how to use a data repository <https://ornl-neutrons.atlassian.net/wiki/spaces/NDPD/pages/19103745/Using+git-lfs+for+test+data>`_
+(login required).
+
 To run the integration tests in your local environment, it is necessary first to download the data files.
 Because of their size, the files are stored in the Git LFS repository
 `usansred-data <https://code.ornl.gov/sns-hfir-scse/infrastructure/test-data/usansred-data>`_.
@@ -75,9 +79,64 @@ After this step, initialize or update the data repository:
 This will either clone `usansred-data` into `/path/to/usanred/tests/usansred-data` or
 bring the `usansred-data`'s refspec in sync with the refspec listed within file `/path/to/usanred/.gitmodules`.
 
-An intro to Git LFS in the context of the Neutron Data Project is found in the
-`Confluence pages <https://ornl-neutrons.atlassian.net/wiki/spaces/NDPD/pages/19103745/Using+git-lfs+for+test+data>`_
-(login required).
+You can make sure all the large files are downloaded by issuing a pull command:
+
+.. code-block:: bash
+
+   $> cd tests/usansred-data
+   $> git checkout main
+   $> git lfs pull
+
+Replacing or adding a file in the data repository
++++++++++++++++++++++++++++++++++++++++++++++++++
+When adding a new test that requires a new data file, or when replacing an existing data file because of
+some update to an existing test.
+
+As an example, consider the data files used in
+`tests/usansred/test_reduce.py::test_main() <https://github.com/neutrons/usansred/blob/next/tests/usansred/test_reduce.py>`_:
+
+.. code-block:: bash
+
+   tests/usansred-data/IPTS-30410/shared/reduced/UN_EmptyPCell_det_1.txt
+   tests/usansred-data/IPTS-30410/shared/reduced/UN_EmptyPCell_det_1_lb.txt
+   tests/usansred-data/IPTS-30410/shared/reduced/UN_EmptyPCell_det_1_unscaled.txt
+   ...
+
+If we wish to replace any of those files with new versions, we simple overwrite the file(s) in the data repository
+with the new versions. For the particular case of `test_reduce.py::test_main()`, the new files would be
+located inside the temporary directory `tmp_path` that is automatically created when the test runs.
+
+.. code-block:: bash
+
+   $> cp /path/to/new/UN_EmptyPCell_det_1.txt tests/usansred-data/IPTS-30410/shared/reduced/UN_EmptyPCell_det_1.txt
+   $> cp /path/to/new/UN_EmptyPCell_det_1_lb.txt tests/usansred-data/IPTS-30410/shared/reduced/UN_EmptyPCell_det_1_lb.txt
+
+Assuming we only wish to modify these two files, the next step is to commit these changes in our local repository
+*usansred-data* and then push the changes to the remote repository.
+
+.. code-block:: bash
+
+   $> cd /path/to/usansred/tests/usansred-data
+   $> git add IPTS-30410/shared/reduced/UN_EmptyPCell_det_1.txt
+   $> git add IPTS-30410/shared/reduced/UN_EmptyPCell_det_1_lb.txt
+   $> git commit -m "Updated data files for test_reduce.py::test_main()"
+   $> git push origin
+
+We're not done yet! The next step is to update the submodule reference in our local *usansred* repository
+and then push the changes to the remote repository.
+
+.. code-block:: bash
+
+   $> cd /path/to/usansred
+   $> git add tests/usansred-data
+   $> git commit -m "Updated usansred-data submodule"
+   $> git push origin
+
+That's it.
+The new data files are now available to all developers who pull the latest changes from the remote repository.
+
+If we want to add a new data file instead of replacing one, the procedure is the same only we won't be
+overwriting any existing files.
 
 
 Coverage reports

docs/source/releases.rst renamed to docs/source/release_notes.rst

@@ -13,6 +13,7 @@ Release Notes
 
 **Of interest to the Developer:**
 
+- PR 17: instructions to add/replace data files
 - PR 15: update Mantid dependency to 6.11
 - PR 14: transition from pip to conda when installing dependency finddata
 - PR 13: Take average of intensity values with duplicate Q AND solve the issue with bg interpolation when bg q and sample q values are too close or identical