FAR's Project Template

This is a Python package cookiecutter template for developing utility libraries at FAR using our standard tool chain:

• uv as the main package management tool.
• ruff for auto-formatting and linting code.
• mypy for type-enforcement
• pytest for building and running test-suites.
• mkdocs and mkdocs Material for writing and building documentation.
• CircleCI for continuous integration.
• pre-commit for automatically running the tool-chain before submitting changes to git.

Features

Automatic updates to the projects generated from this cookiecutter

• Powered by cruft
• Keeps downstream projects up-to-date with best practices as they evolve.

Continuous integration

• Powered by CircleCI.
• This allows for all sorts of automation, including testing, building docs, automated code review, and many other things.

Documentation

• Powered by mkdocs-material
• Auto-generated API documentation from docstrings via mkdocstrings
• See the extensive list of MkDocs plugins which can help you to tune the documentation to fit your project's needs

Automated releases

TODO: Set up an internal PyPI server and allow for an automated release process.

Changelog management

• Gently enforced: Keep a Changelog
• GitHub releases get their description automatically populated based on the changelog content
• The Unreleased section is automatically updated when a release is done
• Changelog is embedded in the documentation

Automation

TODO: Add CircleCI workflows to keep downstream repositories in line with template updates.

Usage

Make sure you have cruft installed. Alternatively, you can use cookiecutter if you are not interested in getting updates to the project "boilerplate" in the future.

Create a new project:

cruft create https://github.com/AlignmentResearch/far-project-template

The CLI interface will ask some basic questions, such the name of the project, and then generate all the goodies automatically.

After that you can make it a proper git repo:

cd <your-project-slug>
git init
git add .
git commit -m "Initial project structure from Python Package cookiecutter"

We update this cookiecutter template regularly to keep it up-to-date with the best practices of the Python world. You can get the updates into your project with:

cruft update

Configure secrets

TODO: Figure out what secrets we need to make automation work and write instructions for their generation and use.