Contributing
Contributing#
Installation#
# Create your own fork of the repository if required and replace whittle-org with your username
git clone git@github.com:whittle-org/whittle.git
cd whittle
pip install -e ".[dev]" # Install what's here (the `.` part) and install the extra dev dependancies
Setup pre-commit to run on every commit
Testing#
Docstring Writing Guidelines#
When adding or updating functions or classes, please ensure that each has a docstring that follows this format:
- Summary: A brief description of what the function or class does.
- args: List each argument with its name, and a short description of its purpose.
- return: Describe the return value, including what it represents. Note: After adding or updating the docstring, ensure that the code passes the following command with no warnings:
Conventional commits and Commitizen#
We use commitizen to manage commits. This enforces conventional commits.
To make a commit, simply run:
This will prompt you to enter a commit message and enforce conventional commit formatting.
If you do not use cz commit or make a commit with a conventional commit message, your PR will not pass CI.
Signing commits#
Note: we recommend using SSH keys for signing commits for convenience (e.g., you can use the same key for commit signing and for authentication to GitHub).
Note: if you don't configure commit signing globally, you will need to use git commit -s/cz commit -s to sign your commits.
<!-- ## Release
Update the version in pyproject.toml first, say to X.Y.Z.
If you maintain a changelog, update it.
This part just makes a versioned commit and tag for github and to be able to easily find code at a specific version. It will also help with versioned documentation to have a tag.
git add pyproject.toml [changelog-file-if-any]
git commit -m "bump: X.Y.Z"
git tag X.Y.Z
git push --tags
git push
Then to release on PyPI:
pip install twine # If not already
rm -rf ./dist # Remove anything currently occupying the dist folder
python -m build --sdist # Build a source distribution
twine upload dist/* # Publish to PyPI
``` -->
## Documentation
View locally
```bash
mkdocs --serve
Build and deploy to GitHub Pages. Make sure to specify the github tag you want to deploy.