|
| 1 | +# Contributing to `codetiming` |
| 2 | + |
| 3 | +Thank you for considering to contribute to `codetiming`. This guide is meant to help you find your way around the project, and let you know which standards that are used. |
| 4 | + |
| 5 | +If you are looking for tutorials or tips on how to use `codetiming`, have a look at the [documentation](https://github.com/realpython/codetiming/blob/master/README.md) and the accompanying article [Python Timer Functions: Three Ways to Monitor Your Code](https://realpython.com/python-timer/). |
| 6 | + |
| 7 | + |
| 8 | +# Reporting Issues or Suggesting New Features |
| 9 | + |
| 10 | +Have you found an issue with `codetiming`, or do you have a suggestion for a new feature? Great! Have a look at the [known issues](https://github.com/realpython/codetiming/issues/new) to see if anyone has reported it already. If not, please post a [new issue](https://github.com/realpython/codetiming/issues/new). |
| 11 | + |
| 12 | +When reporting an issue, please include as much of the following information as possible: |
| 13 | + |
| 14 | +- Your version of `codetiming`: `print(codetiming.__version__)` |
| 15 | +- Your version of Python: `print(sys.version)` |
| 16 | +- Your operating system |
| 17 | +- A description of your issue, ideally including a short code snippet that reproduces the issue |
| 18 | + |
| 19 | +When suggesting a new feature, try to include an example of how your feature could be used. |
| 20 | + |
| 21 | + |
| 22 | +# Contributing Code |
| 23 | + |
| 24 | +Do you want to contribute code to `codetiming`? Fantastic! We welcome contributions as **pull requests**. |
| 25 | + |
| 26 | + |
| 27 | +## Setting Up Your Environment |
| 28 | + |
| 29 | +`codetiming` uses [`flit`](https://flit.readthedocs.io) for package management. You should first install `flit`: |
| 30 | + |
| 31 | +``` |
| 32 | +$ python -m pip install flit |
| 33 | +``` |
| 34 | + |
| 35 | +You can then install `codetiming` locally for development with `flit`: |
| 36 | + |
| 37 | +``` |
| 38 | +$ python -m flit install --pth-file --deps all |
| 39 | +``` |
| 40 | + |
| 41 | +This will install `codetiming` and all its dependencies, including development tools like [`black`](https://black.readthedocs.io) and [`mypy`](http://mypy-lang.org/). The `--pth-file` option allows you to test your changes without reinstalling. On Linux and Mac, you can use `--symlink` for the same effect. |
| 42 | + |
| 43 | + |
| 44 | +## Running Tests |
| 45 | + |
| 46 | +Run tests using [`tox`](https://tox.readthedocs.io/). `tox` helps to enforce the following principles: |
| 47 | + |
| 48 | +- Consistent code style using [`black`](https://black.readthedocs.io). You can automatically format your code as follows: |
| 49 | + |
| 50 | + ``` |
| 51 | + $ black codetiming/ |
| 52 | + ``` |
| 53 | +
|
| 54 | +- Static type hinting using [`mypy`](http://mypy-lang.org/). Test your type hints as follows: |
| 55 | +
|
| 56 | + ``` |
| 57 | + $ mypy --strict codetiming/ |
| 58 | + ``` |
| 59 | +
|
| 60 | + See Real Python's [Python Type Checking guide](https://realpython.com/python-type-checking/) for more information. |
| 61 | +
|
| 62 | +- Unit testing using [`pytest`](https://docs.pytest.org/). You can run your tests and see a coverage report as follows: |
| 63 | +
|
| 64 | + ``` |
| 65 | + $ pytest --cov=codetiming --cov-report=term-missing |
| 66 | + ``` |
| 67 | +
|
| 68 | +Feel free to ask for help in your PR if you are having challenges with any of these tests. |
0 commit comments