|
| 1 | +# CONTRIBUTING |
| 2 | + |
| 3 | +## Asking for help |
| 4 | +If you are looking for help with setting up or using `mons`, or you have other questions about how the program works and how you can contribute, please use the `#modding_help` or `#modding_dev` channels in the Celeste Community Discord: https://discord.gg/celeste |
| 5 | + |
| 6 | +## Before contributing |
| 7 | +- Check the [existing issues](https://github.com/coloursofnoise/mons/issues) to see if your request has already been made. |
| 8 | + - If so, add a comment to describe how you plan to resolve it and request to have the issue assigned to you. |
| 9 | +- If an issue does not already exist, create one describing your request and how you plan on implementing it. |
| 10 | + |
| 11 | +## First time setup |
| 12 | +- Clone the GitHub repository locally |
| 13 | +```console |
| 14 | +$ git clone https://github.com/coloursofnoise/mons.git |
| 15 | +$ cd mons |
| 16 | +``` |
| 17 | +- Create a virtualenv |
| 18 | +```console |
| 19 | +$ python3 -m venv env |
| 20 | +$ . env/bin/activate |
| 21 | +``` |
| 22 | +- Upgrade `pip` and `setuptools` |
| 23 | +```console |
| 24 | +$ python -m pip install --upgrade pip setuptools |
| 25 | +``` |
| 26 | +- Install development dependencies, then install `mons` in editable mode |
| 27 | +```console |
| 28 | +$ pip install -r requirements-dev.txt |
| 29 | +$ pip install -e . |
| 30 | +``` |
| 31 | +- Install the [pre-commit](https://pre-commit.com) hooks |
| 32 | +```console |
| 33 | +$ pre-commit install |
| 34 | +``` |
| 35 | + |
| 36 | +## Writing code |
| 37 | +When making changes to the project, follow best practices for code and version control wherever possible: |
| 38 | +- Commit frequently, with clear commit messages. |
| 39 | +- Use [Black](https://black.readthedocs.io) to format your code. This and other tools will run automatically if you install [pre-commit](https://pre-commit.com) using the instructions above. |
| 40 | +- Add tests to verify your code. Added tests should fail without your changes. |
| 41 | +- Add or update docstrings and other relevant documentation. |
| 42 | +- When creating your pull request, provide a short explanation for your changes and link to the issue being addressed: https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue |
| 43 | + |
| 44 | +## Running tests |
| 45 | +### `pytest` |
| 46 | +Run tests for the current environment with `pytest` |
| 47 | +```console |
| 48 | +$ pytest |
| 49 | +``` |
| 50 | +To run end-to-end tests using a local Celeste install, run `pytest` and provide the path for the Celeste install |
| 51 | + |
| 52 | +:warning: When tests fail they can break the install they are run on. **Do not use a Celeste install you care about.** |
| 53 | +```console |
| 54 | +$ pytest --mons-test-install={/path/to/Celeste/install} |
| 55 | +``` |
| 56 | +### `tox` |
| 57 | +The full suite of tests can be run with `tox`. This will also be run by the CI server when a pull request is submitted |
| 58 | +```console |
| 59 | +$ tox |
| 60 | +``` |
| 61 | +End-to-end tests can also be run with `tox` |
| 62 | +```console |
| 63 | +$ tox -- --mons-test-install={/path/to/Celeste/install} |
| 64 | +``` |
| 65 | + |
| 66 | +# MAINTAINERS |
| 67 | +## Releasing a new version |
| 68 | +- Tag a commit with the format `v{version number}` where {version number} follows the [semver](https://semver.org/) specification. |
| 69 | +- The CI server will run tests, then build and upload the new version to [PyPI](https://pypi.org/project/mons/). |
| 70 | +- (Optional) Create a [GitHub release](https://github.com/coloursofnoise/mons/releases) for the new tag once CI has completed successfully. |
0 commit comments