🌱 Substrate

A modern Copier template for scaffolding Python packages and apps.

🎁 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

✨ 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

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

🍪 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 files specific to Poetry
   rm -f 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!