From ca5fe139797bd2c498614eacb67f1db60a298037 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Thu, 20 Oct 2022 07:49:14 -0700 Subject: [PATCH] update contribution docs (#83) * update contribution docs - made dataset documentation section clearer - fixed typos * add requirements for tests to contributions --- docs/contributing.rst | 46 ++++++++++++++++++++++++++++--------------- 1 file changed, 30 insertions(+), 16 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 5ae859a..899d91b 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -23,19 +23,25 @@ files that are typical of how the specific code is run. .. _`alchemtest/gmx/benzene`: https://github.com/alchemistry/alchemtest/tree/master/src/alchemtest/gmx/benzene -Documentation -------------- - -Add - -* a brief explanation of how you would analyze the data with alchemlyb - or your own tool (show Python commands or the full command with - options so that we can reproduce) and -* the value(s) that you get so that we know the ground truth. - -Comment on what to look out for in the output files (knowing what is -what in the files helps). If you have *links to where the format is -defined*, please let us know. +Data set description +-------------------- + +For your data set, you should be able to include the following in a +brief description (which will become part of the data set and the +documentation as described in more detail in :ref:`process`): + +* Include the value(s) that you get when analyzing the data set + yourself so that we know the ground truth. + + It is very helpful if you include a brief explanation of how you + analyze the data with alchemlyb or your own tool (show Python commands + or the full command with options so that one can reproduce the + analysis if necessary). +* State how the data set was generated. Include the temperature. +* Comment on what to look out for in the output files, e.g., special + sampling options. +* For **new file formats:** Include information about the file format + definition, such as *links* or *paper citations*. In general, follow the example of the existing data sets (especially similar data sets or for the same MD/MC code) and discuss the specfics @@ -107,7 +113,7 @@ Process description text is added the *DESCR* key. Again, copy an existing function and modify. - * Add an ``from .access import load load_MYDATASET`` to the + * Add an ``from .access import load_MYDATASET`` to the top-level :file:`__init__.py` to make your accessor function part of alchemtest. 4. Locally test that you can load your dataset:: @@ -136,11 +142,19 @@ Process 5. Create a `Pull Request`_ with your new code and files. -6. Engage in the code review — we might have questions, suggestions, +6. Add a *test* that checks that your files can be found. Look in the + :file:`src/alchemtest/tests` directory and follow the examples that + are already there. + We are also happy to help you with this step — just ask. + + You can run the tests locally with `pytest` and you will also see + that the tests are run on your PR. + +7. Engage in the code review — we might have questions, suggestions, and requests for revisions to ensure that your contribution fits into the library. -7. Once your PR is accepted it will be merged by a developer and your +8. Once your PR is accepted it will be merged by a developer and your dataset is part of **alchemtest** — Congratulations!