permit-power

Project for Permit Power

• Github repository: https://github.com/switchbox-data/permit-power/
• Documentation https://switchbox-data.github.io/permit-power/

Getting started with your project

1. Create a New Repository

First, create a repository on GitHub with the same name as this project, and then run the following commands:

git init -b main
git add .
git commit -m "init commit"
git remote add origin git@github.com:switchbox-data/permit-power.git
git push -u origin main

2. Set Up Your Development Environment

If you installed devcontainers, simply open up this repo with VSCode and you'll be prompted to build and open the container.

If you prefer to work outside of a container, install the environment and the pre-commit hooks with

just install

This will also generate your uv.lock file

3. Run the pre-commit hooks

Initially, the CI/CD pipeline might be failing due to formatting issues. To resolve those run:

uv run pre-commit run -a

4. Commit the changes

Lastly, commit the changes made by the two steps above to your repository.

git add .
git commit -m 'Fix formatting issues'
git push origin main

5. Finishing setting up tools

For activating the automatic documentation with MkDocs, see here.

6. Clean up README

You are now ready to start development on your project!

Please delete the "Getting started with your project" of this README.

Development commands

To simplify development, this project uses the just command runner for all major tasks.

Available commands are defined in Justfile. To view available them:

just

or

just --list

Setting up development environment

With devcontainers

Given that many projects require system dependencies, the easiest way to define and distribute a reproducible development environment is with devcontainers.

To load this project's devcontainer, open up the repo in VSCode (or a VSCode fork like Cursor or Positron.)

The editor will auto-detect the presence of the repo's devcontainer (configured in .devcontainer/devcontainer.json). Click "Reopen in Container" to launch the devcontainer. uv will install python packages inside the container.

With uv

This package uses uv for managing python versions, virtual environments, and packages.

First, install just.

Then, you can install uv, install the pre-commit hooks, launch the virtualenv, and download the packages (pinned in uv.lock) by running:

just install

Adding a package

To add a python package to the project:

uv add <package-name>

This replaces pip install <package-name>, and has the effect of adding the package to pyproject.toml, as well as pinning the package version in uv.lock.

Adding a development tool

To add a package that will only be used as a development tool:

uv add --dev <package-name>

This will update the dev dependency-groups in pyproject.toml, and ensure that the package isn't declared as a run-time dependency of the library itself.

Running code quality checks

We use ruff for linting and code formatting, ty for type checking, and a series of post-commit hooks for validating YAML, JSON, whitespaces, and so on.

To run code quality checks:

just check

The checks will also be run automatically by Github Actions when opening PRs, merging to main, or creating a new release.

Running tests

Our test are written using pytest and live in tests/. They are checked against multiple python versions using tox.

To run the tests:

just test

Rendering docs

We use mkdocs and mkdocs-material for writing and rendering docs. The docs are written in markdown and live in docs/.

To dynamically render the docs as you develop them:

just docs

To statically render the docs into HTML:

just docs-test

The docs are served by Github Pages out of the gh-pages branch. We do not publish them manually: they are automatically rendered and published by the Github Actions workflow when merging to main.

Triggering the CI/CD pipeline

We use Github Actions to run tests, run code quality checks, and publish docs when you open a pull request, merge to main, or when you create a new release.

The Github Action workflows live in .github/worksflows.

---

Repository initiated with switchbox-data/cookiecutter-sb, based off of fpgmaas/cookiecutter-uv.