Contributing - Snailz Docs

Skip to content

# Contributing

Contributions are very welcome. Please file issues or submit pull requests in our GitHub repository. All contributors will be acknowledged, but must abide by our Code of Conduct.

## Please

- Use Conventional Commits.
- Open an issue before creating a pull request.

## Setup

1. Fork or clone the repository.
2. `uv sync --extra dev" to install an editable version of this package along with all its dependencies (including developer dependencies).
3. Use `uv run COMMAND` to run commands in the virtual environments. In particular, use `uv run doit list` to see available commands and `uv run doit COMMAND` to run a command.

Alternatively:

1. Create a fresh Python environment: `uv venv`
2. Activate that environment: `source .venv/bin/activate`
3. Install dependencies and editable version of package: `uv pip install -e '.[dev]'`

## Actions

`uv run doit list` prints a list of available commands.

Command | Action
--- | ---
all | Regenerate all data using example parameters.
assays | Generate sample assays file.
build | Build the Python package in the current directory.
coverage | Run tests with coverage.
docs | Generate documentation using MkDocs.
format | Reformat code.
grid | Generate sample grid file.
init | Regenerate default parameters.
lint | Check the code format.
mangle | Mangle generated assay files.
people | Generate sample people file.
specimens | Generate sample specimens file.
test | Run tests.
tidy | Clean all build artifacts.
typing | Check types with pyright.

## Publishing

Use `twine upload --verbose -u __token__ -p pypi-your-access-token dist/*`.

## Tooling

- The command-line interface to Claude. I'm disgusted by the amorality of the AI industry, but am now convinced that the coding tools are here to stay: writing tests and refactoring code with Claude's help was much faster than doing it by hand.

- `uv` for managing the packages and virtual environment and for running commands. It's the first time I've used it as itself rather than running `uv pip whatever`; never going back.

- `ruff` and `pyright` for checking the code. `ruff` is a joy, but checking type annotations with `pyright` cost me a couple of hours. It's not the tool's fault, though: figuring out how to annotate the last 5% of the code led to me writing my first protocol and then throwing up my hands and replacing it with `Any`.

- `pydantic` for storing and validating records, including the data that `snailz` generates and the parameters used in generation. I started with `dataclasses`, but switched as soon as I found myself1 adding methods that `pydantic` already had.

- `doit` to run commands instead of Make. I'm more comfortable with the latter, but I recognize that writing Makefiles is a dying art.

- `mkdocs` for documentation instead of Sphinx or `pdoc`2. I find `mkdocs` easier to work with than Sphinx, and `pdoc` doesn't support "extra" Markdown pages as well as `mkdocs`. (If the folks at Astral are looking for new product ideas, a better documentation generator would have at least one paying customer the day it launched…)

- `pytest`, `pyfakefs`, and `faker` for testing and `click` for building the command-line interface instead of `argparse`.

1. Well, myself and Claude… ↩

2. Please don't ever use `pdoc3`: someone who picks a swastika as a project logo and then argues that it's just a cultural symbol doesn't deserve your downloads. ↩