🌱 Substrate

A modern Copier template for scaffolding Python packages and apps.

demo.mov

🎁 Features

• 🧑‍💻 One-click development environments with Dev Containers and GitHub Codespaces
• 🌈 Cross-platform support for Linux, macOS, and Windows
• 🐚 Modern shell prompt with Starship
• 📦 Packaging and dependency management with uv
• 🚚 Installing from and publishing to PyPI
• ⚡️ Task running with Poe the Poet
• 💅 Code formatting with Ruff
• ✅ Code linting with Pre-commit, Mypy, and Ruff
• 🏷 Optionally follow the Conventional Commits standard
• 🚦 Release new versions with Semantic Versioning and Keep A Changelog using Commitizen
• 💌 Verified commits with GPG
• ♻️ Continuous integration with GitHub Actions or GitLab CI/CD
• 🧪 Test coverage with Coverage.py
• 🧰 Dependency updates with Dependabot
• 📚 Documentation with MkDocs

✨ Using

Tip

You should first install uv to be able to run the commands below.

Create a new Python project

To create a new Python project with this template, run:

uvx copier copy gh:superlinear-ai/substrate path/to/local/repository

Update your Python project

To update your Python project to the latest template version, run:

uvx copier update --exclude src/ --exclude tests/

Release a new version of your Python project

If you have enabled Conventional Commits, you can create a new version tag and update CHANGELOG.md based on your commit messages with:

git checkout main
cz bump
git push origin main --tags

Build and publish your Python project's docs

To build and serve your Python project's docs, run:

poe docs --serve

If your project is on GitHub, your docs will be published automatically to GitHub Pages every time you update the default branch. You can view the docs by clicking on the badge in your project's README.

Tip

Make sure to configure the source of your project's GitHub Pages as GitHub Actions in your project settings to allow the GitHub Actions workflow to publish your docs.

🍪 Migrating from Cookiecutter

Important

This project was formerly known as Poetry Cookiecutter and was based on Poetry and Cookiecutter. We will continue to support the original Cookiecutter-based template side by side with the new Copier-based template. However, we do encourage users to upgrade to the new Copier-based template by following the instructions below.

To migrate a project from Cookiecutter to Copier, follow these steps:

1. In your project repository, run:

   # Create a new branch
   git checkout -b rescaffold
   
   # Remove unnecessary files
   rm -f .cruft.json poetry.lock
   
   # Rescaffold the project without changing src/ and tests/
   uvx copier copy --overwrite --exclude src/ --exclude tests/ gh:superlinear-ai/substrate .

2. Review the changes to pyproject.toml and reinsert your project's dependencies.

3. Review the changes to README.md and reinsert your project's documentation.

4. Commit and push all changes with:

   # Stage all changes
   git add .
   
   # Commit the staged changes
   git commit -m "build: upgrade scaffolding"
   
   # Push the committed changes
   git push origin rescaffold

5. Create a PR from your branch, review it, and merge it!

Contributing

Prerequisites

1. Generate an SSH key and add the SSH key to your GitHub account.

2. Configure SSH to automatically load your SSH keys:

   cat << EOF >> ~/.ssh/config
   
   Host *
     AddKeysToAgent yes
     IgnoreUnknown UseKeychain
     UseKeychain yes
     ForwardAgent yes
   EOF

3. Install Docker Desktop.

4. Install VS Code and VS Code's Dev Containers extension. Alternatively, install PyCharm.

5. Optional: install a Nerd Font such as FiraCode Nerd Font and configure VS Code or PyCharm to use it.

Development environments

The following development environments are supported:

1. ⭐️ GitHub Codespaces: click on Open in GitHub Codespaces to start developing in your browser.

2. ⭐️ VS Code Dev Container (with container volume): click on Open in Dev Containers to clone this repository in a container volume and create a Dev Container with VS Code.

3. ⭐️ uv: clone this repository and run the following from root of the repository:

   # Create and install a virtual environment
   uv sync
   
   # Activate the virtual environment
   source .venv/bin/activate
   
   # Install the pre-commit hooks
   pre-commit install --install-hooks

4. VS Code Dev Container: clone this repository, open it with VS Code, and run Ctrl/⌘ + ⇧ + P → Dev Containers: Reopen in Container.

5. PyCharm Dev Container: clone this repository, open it with PyCharm, create a Dev Container with Mount Sources, and configure an existing Python interpreter at /opt/venv/bin/python.

Developing

• This project follows the Conventional Commits standard to automate Semantic Versioning and Keep A Changelog with Commitizen.
• Run cz bump to bump Substrate's version, update the CHANGELOG.md, and create a git tag. Then push the changes and the git tag with git push origin main --tags.