1.. _contributing: 2 3Contributing to Pint 4==================== 5 6Pint uses (and thanks): 7 8- github_ to host the code 9- travis_ to test all commits and PRs. 10- coveralls_ to monitor coverage test coverage 11- readthedocs_ to host the documentation. 12- `bors-ng`_ as a merge bot and therefore every PR is tested before merging. 13- black_, isort_ and flake8_ as code linters and pre-commit_ to enforce them. 14- pytest_ to write tests 15- sphinx_ to write docs. 16 17You can contribute in different ways: 18 19Report issues 20------------- 21 22You can report any issues with the package, the documentation to the Pint `issue tracker`_. 23Also feel free to submit feature requests, comments or questions. 24 25 26Contribute code 27--------------- 28 29To contribute fixes, code or documentation to Pint, fork Pint in github_ and submit 30the changes using a pull request against the **master** branch. 31 32- If you are submitting new code, add tests (see below) and documentation. 33- Write "Closes #<bug number>" in the PR description or a comment, as described in the 34 `github docs`_. 35- Log the change in the CHANGES file. 36- Execute ``pre-commit run --all-files`` and resolve any issues. 37 38In any case, feel free to use the `issue tracker`_ to discuss ideas for new features or improvements. 39 40Notice that we will not merge a PR if tests are failing. In certain cases tests pass in your 41machine but not in travis. There might be multiple reasons for this but these are some of 42the most common 43 44- Your new code does not work for other Python or Numpy versions. 45- The documentation is not being built properly or the examples in the docs are 46 not working. 47- linters are reporting that the code does no adhere to the standards. 48 49 50Setting up your environment 51--------------------------- 52 53If you're contributing to this project for the fist time, you can set up your 54environment on Linux or OSX with the following commands:: 55 56 $ git clone git@github.com:hgrecco/pint.git 57 $ cd pint 58 $ python -m virtualenv venv 59 $ source venv/bin/activate 60 $ pip install -e . 61 $ pip install -r requirements_docs.txt 62 $ pip install pre-commit # This step and the next are optional but recommended. 63 $ pre-commit install 64 65 66Writing tests 67------------- 68 69We use pytest_ for testing. If you contribute code you need to add tests: 70 71- If you are fixing a bug, add a test to `test_issues.py`, or amend/enrich the general 72 test suite to cover the use case. 73- If you are adding a new feature, add a test in the appropiate place. There is usually 74 a `test_X.py` for each `X.py` file. There are some other test files that deal with 75 individual/specific features. If in doubt, ask. 76- Prefer functions to classes. 77- When using classes, derive from `QuantityTestCase`. 78- Use `parametrize` as much as possible. 79- Use `fixtures` (see conftest.py) instead of instantiating the registry yourself. 80- Checkout `helpers.py` for some convenience functions before reinventing the wheel. 81- When your test does not modify the registry, use `sess_registry` fixture. 82 83 84Running tests and building documentation 85---------------------------------------- 86 87To run the test suite, invoke pytest from the ``pint`` directory:: 88 89 $ cd pint 90 $ pytest 91 92To run the doctests, invoke Sphinx's doctest module from the ``docs`` directory:: 93 94 $ cd docs 95 $ make doctest 96 97To build the documentation, invoke Sphinx from the ``docs`` directory:: 98 99 $ cd docs 100 $ make html 101 102Extension Packages 103------------------ 104 105Pint naturally integrates with other libraries in the scientific Python ecosystem, and 106a small number of 107`extension/compatibility packages<numpy.html#Compatibility-Packages>`_ have arisen to 108aid in compatibility between certain packages. Pint's rule of thumb for integration 109features that work best as an extension package versus direct inclusion in Pint is: 110 111* Extension (separate packages) 112 113 * Duck array types that wrap Pint (come above Pint in 114 `the type casting hierarchy<numpy.html#Technical-Commentary>`_) 115 116 * Uses features independent/on top of the libraries 117 118 * Examples: xarray, Pandas 119 120* Integration (built in to Pint) 121 122 * Duck array types wrapped by Pint (below Pint in the type casting hierarchy) 123 124 * Intermingling of APIs occurs 125 126 * Examples: Dask 127 128 129.. _github: http://github.com/hgrecco/pint 130.. _`issue tracker`: https://github.com/hgrecco/pint/issues 131.. _`bors-ng`: https://github.com/bors-ng/bors-ng 132.. _`github docs`: https://help.github.com/articles/closing-issues-via-commit-messages/ 133.. _travis: https://travis-ci.com/ 134.. _coveralls: https://coveralls.io/ 135.. _readthedocs: https://readthedocs.org/ 136.. _pre-commit: https://pre-commit.com/ 137.. _black: https://black.readthedocs.io/en/stable/ 138.. _isort: https://pycqa.github.io/isort/ 139.. _flake8: https://flake8.pycqa.org/en/latest/ 140.. _pytest: https://docs.pytest.org/en/stable/ 141.. _sphinx: https://www.sphinx-doc.org/en/master/ 142