Contributing¶

This is a personal, very-part-time project, largely driven by my own opinions about how best to configure a Python code base.

Contributions as described below are welcome.

Reporting bugs¶

If something isn’t working as described, or if you find a mistake in the documentation, please feel free to report a bug by opening an issue.

Contributing to the code base¶

Contributions to the code base are welcome. If you want to add a new feature, please open an issue first. Because pyprefab is an opinion-drive personal project, it’s best to make sure our opinions are aligned before doing any work!

If you’d like to tackle an existing issue, please leave a comment on it.

Creating your local development environment¶

For contributing to this code base, you’ll need:

A GitHub account
Git installed on your machine
uv

[!IMPORTANT] If you have an active Python virtual environment (for example, conda’s base environment), you’ll need to deactivate it before following the instructions below.

Configure git¶

On GitHub, fork this repository.

Clone the forked repository to your machine:

git clone https://github.com/<username>/pyprefab.git
cd pyprefab

optional: Set the upstream remote to sync your fork with the pyprefab repository:

git remote add upstream https://github.com/bsweger/pyprefab.git
git fetch upstream

Install project and dependencies¶

From the root of the repo, create a virtual environment and install the project dependencies. The uv sync command handles installing Python, creating a virtual environment, and installing project dependencies.
```
uv sync
```
(More information about how uv finds or downloads a Python interpreter)
Run the nox-based checks to ensure that everything works correctly:

[!TIP] Prefixing python commands with uv run instructs uv to run the command in the project’s virtual environment, even if you haven’t explicitly activated it.
```
uv run nox --tags checks
```
The above command will run the checks against every version of Python supported by pyprefab. Alternately, you could save time by running the checks against a specific version of Python:
```
uv run nox --tags checks --python 3.13
```
GitHub actions will run the checks against all Python versions when you open a pull request.

Make your changes¶

Once your development environment is set up, you can start making your changes. Note that you can test your work in progress by running individual nox sessions as you go:

nox -s lint - Run the linter (ruff)
nox -s typecheck - Run static type checking (mypy)
nox -s tests - Run the test suite (will run on all supported Python versions)
nox -s docs - Build the documentation
nox -s docs_serve - Serve the documentation locally with auto-reload

To run a specific session with a specific Python version:

nox -s test-3.11

Updating your development environment¶

If time has passed between your initial project setup and when you make changes to the code, make sure your fork and development environment are up-to-date.

Sync your fork to the upstream repository:

git checkout main
git fetch upstream
git rebase upstream/main
git push origin main

Update your project dependencies:
```
uv sync
```

Adding project dependencies¶

If your change requires a new dependency, add it as follows:

uv add <dependency>

The uv add command will:

Add the dependency to pyproject.toml
Install the dependency into the project’s virtual environment
Update the project’s lockfile (uv.lock)

Make sure to commit the updated versions of pyproject.toml and uv.lock.

Updating snapshot tests¶

This project uses syrupy to run snapshot tests against the output of pyprefab’s templates.

If you’ve added a new pyprefab template, add a test snapshot test for it in test_templates.py. Then, instruct syrupy to generate a snapshot for the new template:

uv run pytest --snapshot-update

Updating documentation¶

This project uses Sphinx and MyST-flavored markdown for documentation.

Documentation updates should be made in docs/source. To preview changes:

uv run nox -s docs_serve

The output of the above command provides a URL for viewing the documentation via a local server (usually http://127.0.0.1:8000).

Submitting code changes¶

After you’ve completed the changes described in the issue you’re working on, you can submit them by creating a pull request (PR) in the pyprefab repository.

Please ensure the following are true before creating the PR:

Your change is covered by tests, if applicable
Project documentation is updated, if applicable
All nox checks pass: uv run nox --tags checks
The [Unreleased] section of CHANGELOG.md contains a description of your change.

The PR itself should:

Have a descriptive title
Be linked to its corresponding issue in the description.
Have a description that includes any other information or context that will help a code reviewer understand your changes.

Releasing to PyPI (maintainers only)¶

Use the instructions below to create a new pyprefab release and publish it to PyPI. The directions assume that your git client is set up to sign commits by default.

This process should be done on a local machine, since the web version of GitHub doesn’t support creating signed tags.

Merge an update to CHANGELOG.md, changing Unreleased to the new version.
From the repo’s main branch, create a signed tag for the release number and add a message when prompted. For example:
```
git tag -s v0.5.6
```
Push the tag upstream:
```
git push origin
```

Once the tag is pushed, the publish-pypi.yaml workflow will build the package, publish it to PyPI (after manual approval), and create a GitHub release.