Contributing¶

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

Environment setup¶

Fork and clone the repository:

git clone https://github.com/AllenInstitute/npc_io
cd npc_io

Create a new virtual environment:
conda is convenient for getting a specific Python version, but adds additional packages
it's preferable to use a completely clean environment to properly test the project's specified dependencies in isolation
where possible, use the lowest supported Python version (specified in pyproject.toml project/requires-python)
```
python3 -m venv .venv
```
Activate the environment:
Windows
```
.venv\scripts\activate
```
Unix
```
source .venv/bin/scripts/activate
```
Add PDM to manage the project's dependencies and run pre-build jobs:
```
pip install pdm
pdm install
```

You now have an editable pip install of the project, with all dev dependencies. The following should work:

python -c "import npc_io; print(npc_io.__version__)"

Using PDM¶

The project uses PDM for reproducible dev environments, with pre-defined pyproject.toml configuration for tools While working on the project, use PDM to manage dependencies: - add dependencies: pdm add numpy pandas - add dev dependencies: pdm add -G dev mypy - remove dependencies correctly: pdm remove numpy # does nothing because pandas still needs numpy! - update the environment to reflect changes in pyproject.toml: pdm update Always commit & push pdm.lock to share the up-to-date dev environment

Development (internal contributors)¶

Edit the code and/or the documentation on the main branch
Add simple doctests to functions or more elaborate tests to modules in tests
If you updated the project's dependencies (or you pulled changes):
run pdm update
if it fails due to dependencies you added, follow any error messages to resolve dependency version conflicts
when it doesn't fail, commit any changes to pdm.lock along with the changes to pyproject.toml
Run tests with pdm run test
mypy will check all functions that contain type annotations in their signature
pytest will run doctests and any tests in the tests dir
If you updated the documentation or the project dependencies:
run pdm run doc
go to http://localhost:8000 and check that everything looks good
if you are unsure about how to fix a test, just push your changes - the continuous integration will fail on Github and someone else can have a look
don't update the changelog, it will be taken care of automatically
link to any related issue number in the Commit message: Fix variable name #13
pull changes with git pull --rebase to keep the commit history easy to read

Updating from the original template¶

With a clean working directory, run pipx run copier update --defaults.

See here for more info.