Skip to content

Commit

Permalink
update contribution docs (#83)
Browse files Browse the repository at this point in the history
* update contribution docs

- made dataset documentation section clearer
- fixed typos

* add requirements for tests to contributions
  • Loading branch information
orbeckst authored Oct 20, 2022
1 parent bd4d61a commit ca5fe13
Showing 1 changed file with 30 additions and 16 deletions.
46 changes: 30 additions & 16 deletions docs/contributing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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::
Expand Down Expand Up @@ -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!


Expand Down

0 comments on commit ca5fe13

Please sign in to comment.