diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index b1988e3ec..ba7001912 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,4 +1,4 @@ Please go the the `Preview` tab and select the appropriate PR template: -* [Default template](?expand=1&template=pull_request_template.md) -* [Adding a new architecture](?expand=1&template=pull_request_new-architecture.md) +- [Default template](?expand=1&template=pull_request_template.md) +- [Adding a new architecture](?expand=1&template=pull_request_new-architecture.md) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 000000000..5f50dbdf3 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,131 @@ +.. _contributing: + +Contributing +============ +🎉 First off, thanks for taking the time to contribute to metatensor-models! 🎉 + +If you want to contribute but feel a bit lost, do not hesitate to contact us and ask +your questions! We will happily mentor you through your first contributions. + +Area of contributions +--------------------- +The first and best way to contribute to metatensor-models is to use it and advertise it +to other potential users. Other than that, you can help with: + +- documentation: correcting typos, making various documentation clearer; +- bug fixes and improvements to existing code; +- adding new architectures +- and many more ... + +All these contributions are very welcome. We accept contributions via Github `pull +request `_. If you want to work on the code +and pick something easy to get started, have a look at the `good first issues +`_. + + +Bug reports and feature requests +-------------------------------- +Bug and feature requests should be reported as `Github issues +`_. For bugs, you should provide +information so that we can reproduce it: what did you try? What did you expect? What +happened instead? Please provide any useful code snippet or input file with your bug +report. + +If you want to add a new feature to metatensor-models, please create an `issue +`_ so that we can discuss it, +and you have more chances to see your changes incorporated. + + +Contribution tutorial +--------------------- +In this small tutorial, you should replace `` as needed. If anything is +unclear, please ask for clarifications! There are no dumb questions. + +Getting started +--------------- +To help with developing start by installing the development dependencies: + +.. code-block:: bash + + pip install tox + + +Then this package itself + +.. code-block:: bash + + git clone https://github.com/lab-cosmo/metatensor-models cd metatensor-models pip + install -e . + +This install the package in development mode, making it importable globally and allowing +you to edit the code and directly use the updated version. To see a list of all +supported tox environments please use + +.. code-block:: bash + + tox list + +Running the tests +----------------- +The testsuite is implemented using Python's `unittest`_ framework and should be set-up +and run in an isolated virtual environment with `tox`_. All tests can be run with + +.. code-block:: bash + + tox # all tests + +If you wish to test only specific functionalities, for example: + +.. code-block:: bash + + tox -e lint # code style + tox -e tests # unit tests of the main library + tox -e examples # test the examples + + +You can also use ``tox -e format`` to use tox to do actual formatting instead of just +testing it. Also, you may want to setup your editor to automatically apply the `black +`_ code formatter when saving your files, there +are plugins to do this with `all major editors +`_. + +If you want to test a specific archicture you can also do it. For example + +.. code-block:: bash + + tox -e soap-bpnn-tests + +Will run the unit and regression tests for the :ref:`SOAP-BPNN ` +model. Note that architecture tests are not run by default if yiu just type ``tox``. + +.. _unittest: https://docs.python.org/3/library/unittest.html +.. _tox: https://tox.readthedocs.io/en/latest + +Contributing to the documentation +--------------------------------- +The documentation is written in reStructuredText (rst) and uses `sphinx`_ documentation +generator. In order to modify the documentation, first create a local version on your +machine as described above. Then, build the documentation with + +.. code-block:: bash + + tox -e docs + +You can then visualize the local documentation with your favorite browser using the +following command (or open the :file:`docs/build/html/index.html` file manually). + +.. code-block:: bash + + # on linux, depending on what package you have installed: + xdg-open docs/build/html/index.html + firefox docs/build/html/index.html + + # on macOS: + open docs/build/html/index.html + +.. _`sphinx` : https://www.sphinx-doc.org + +Contributing new architectures +------------------------------ +If you want to contribute a new model pleas read the pages on +:ref:`architecture-life-cycle` and :ref:`adding-new-architecture`. diff --git a/docs/src/dev-docs/architecture-life-cycle.rst b/docs/src/dev-docs/architecture-life-cycle.rst index b3cb14a57..96dcd35f8 100644 --- a/docs/src/dev-docs/architecture-life-cycle.rst +++ b/docs/src/dev-docs/architecture-life-cycle.rst @@ -1,3 +1,5 @@ +.. _architecture-life-cycle: + Life Cycle of an Architecture ============================= diff --git a/docs/src/dev-docs/getting-started.rst b/docs/src/dev-docs/getting-started.rst new file mode 100644 index 000000000..9e6610243 --- /dev/null +++ b/docs/src/dev-docs/getting-started.rst @@ -0,0 +1,3 @@ +.. _label_dev-getting-started: + +.. include:: ../../../CONTRIBUTING.rst diff --git a/docs/src/dev-docs/index.rst b/docs/src/dev-docs/index.rst index b2610a9a8..8b2a02ea2 100644 --- a/docs/src/dev-docs/index.rst +++ b/docs/src/dev-docs/index.rst @@ -9,6 +9,7 @@ module. .. toctree:: :maxdepth: 1 + getting-started architecture-life-cycle new-architecture cli/index