Rhiza

Strong roots

Creating and maintaining technical harmony across repositories.

A collection of reusable configuration templates for modern Python projects. Save time and maintain consistency across your projects with these pre-configured templates.

In the original Greek, spelt ῥίζα, pronounced ree-ZAH, and having the literal meaning root.

🌟 Why Rhiza?

Unlike traditional project templates (like cookiecutter or copier) that generate a one-time snapshot of configuration files, Rhiza provides living templates that evolve with your project. Classic templates help you start a project, but once generated, your configuration drifts away from the template as best practices change. Rhiza takes a different approach: it enables continuous synchronization, allowing you to selectively pull template updates into your project over time through automated workflows. This means you can benefit from improvements to CI/CD workflows, linting rules, and development tooling without manually tracking upstream changes. Think of it as keeping your project's foundation fresh and aligned with modern practices, while maintaining full control over what gets updated.

Rhiza and rhiza-cli

Rhiza has two distinct components:

• rhiza (this repository) — the template content: the curated set of configuration files, Makefile modules, CI/CD workflows, and tooling files that downstream projects sync from.
• rhiza-cli — the CLI engine: a separate Python package (installed on-the-fly via uvx) that provides the rhiza command and implements operations such as init, sync, bump, and release.

In short: rhiza is the what (the template files you receive); rhiza-cli is the how (the tool that fetches and applies them).

When you run uvx rhiza init or uvx rhiza sync, you are invoking the rhiza-cli package — it reads your .rhiza/template.yml and syncs the matching files from this repository (or your own fork) into your project. The two components are versioned independently, so templates and the CLI can be updated separately.

How It Works

Rhiza uses a simple configuration file (.rhiza/template.yml) to control which templates sync to your project. The recommended approach is to select a profile — a named preset for common project contexts — or to select individual bundles for full control:

# .rhiza/template.yml — profile-based (recommended)
repository: Jebel-Quant/rhiza
ref: v0.14.0

profiles:
  - github-project

# .rhiza/template.yml — bundle-based (advanced)
repository: Jebel-Quant/rhiza
ref: v0.14.0

templates:
  - core
  - tests
  - github
  - github-tests
  - docker

What you're seeing:

• repository - The upstream template source (can be any repository, not just Rhiza!)
• ref - Which version tag/branch to sync from (e.g., v0.14.0 or main)
• profiles - Named presets that expand to a set of bundles (see Profiles below)
• templates - Individual template bundles for advanced or additional selection

For advanced use cases you can still use explicit include/exclude file patterns alongside or instead of bundles:

# Advanced: file-pattern based selection
include: |
  .github/workflows/*.yml
  ruff.toml

exclude: |
  .rhiza/make.d/custom-task.mk

💡 Automated Updates: When using a version tag (e.g., v0.7.1) instead of a branch name, Renovate will automatically create pull requests to update the ref field when new versions are released. This keeps your templates up-to-date with minimal manual intervention.

To enable this in your project, copy the regexManagers configuration from this repository's renovate.json file into your own Renovate configuration. See the linked configuration for the complete setup.

When you run uvx rhiza sync or trigger the automated sync workflow, Rhiza fetches only the files matching your include patterns, skips anything in exclude, and creates a clean diff for you to review. You stay in control of what updates and when.

💡 Pro Tip: While you can use Jebel-Quant/rhiza directly, we recommend creating your own template repository using GitHub's "Use this template" button. This gives you a clean copy to customise for your organisation's specific needs and constraints—adjusting CI workflows, coding standards, or tooling choices—while still benefiting from Rhiza's sync mechanism. Your template repo becomes your team's source of truth, and you can selectively pull updates from upstream Rhiza when desired.

📚 Table of Contents

• Why Rhiza?
• Quick Start
• What You Get
• Available Templates
• Integration Guide
• Available Tasks
• Advanced Topics
• CI/CD Support
• Project Maintainability
• Learning Resources
• Contributing to Rhiza

🚀 Quick Start

# Navigate to your project directory
cd /path/to/your/project

# Initialise Rhiza configuration and pick your bundles
uvx rhiza init

# Edit .rhiza/template.yml to review the bundle selection, then apply
uvx rhiza sync

See the Integration Guide for more options, or follow the step-by-step tutorial in rhiza-education (Lessons 6–8).

For Contributing to Rhiza

If you want to develop Rhiza itself:

# Clone the repository
git clone https://github.com/jebel-quant/rhiza.git
cd rhiza

# Install dependencies
make install

✨ What You Get

Adopt a Rhiza bundle and your project immediately gains:

• Makefile with 40+ targets for install, test, fmt, release, docs, and more
• CI/CD workflows for GitHub Actions and/or GitLab CI — test, lint, release, sync
• Pre-commit hooks — ruff, bandit, markdownlint, interrogate, actionlint, and more
• pytest with coverage, benchmarks, and property-based testing via Hypothesis
• Documentation via MkDocs + zensical, with optional Marimo notebook exports
• Release automation — version bumping, OIDC PyPI publishing, optional grayskull conda recipe generation (vars.PUBLISH_CONDA, defaults to true), SLSA provenance
• Security scanning — CodeQL, bandit, secret scanning, Dependabot
• Shell completions for bash and zsh (tab-complete all make targets)

📝 Architecture Decision Records

This project maintains Architecture Decision Records (ADRs) to document important architectural and design decisions.

ADRs help preserve the reasoning behind key decisions, making it easier for current and future contributors to understand why the project is structured the way it is.

Browse ADRs: See docs/adr/ for all architecture decisions.

Key decisions documented:

• ADR-0001: Use Architecture Decision Records
• ADR-0002: Use uv for Python Package and Environment Management
• ADR-0003: Use Ruff for Linting and Formatting
• ADR-0004: Adopt a Modular Makefile Architecture
• ADR-0005: Separate rhiza Template Repository from rhiza-cli
• ADR-0006: Organise Templates into Bundles
• ADR-0007: Support Dual CI/CD with GitHub Actions and GitLab CI
• ADR-0008: Use Marimo for Interactive Notebooks
• ADR-0009: Use Pre-commit Hooks for Automated Code Quality Enforcement

Create a new ADR: Copy the template in docs/adr/, give it the next number, and open a pull request for review.

For more information about the ADR format and how to create new records, see the ADR README.

📁 Available Templates

• 🚀 CI/CD Templates - Ready-to-use GitHub Actions and GitLab CI workflows
• 🧪 Testing Framework - Comprehensive test setup with pytest
• 📚 Documentation - Automated documentation site via MkDocs + zensical, with optional Marimo notebook exports
• 🔍 Code Quality - Linting with ruff, formatting, and dependency checking with deptry
• 📝 Editor Configuration - Cross-platform .editorconfig for consistent coding style
• 📊 Marimo Integration - Interactive notebook support for documentation and exploration
• 🎤 Presentations - Generate slides from Markdown using Marp
• 🐳 Containerization - Docker and Dev Container configurations

Profiles (Recommended Starting Point)

Rhiza provides profiles — named presets that select a sensible set of bundles for common project contexts. Profiles are the recommended way to get started.

Profile	Description	Includes
local	Local-first development with no hosted CI/CD workflow files	core, book, marimo, tests
github-project	GitHub-hosted project with CI/CD and release automation	core, github, book, marimo, tests, github-book, github-marimo, github-tests
gitlab-project	GitLab-hosted project with GitLab CI/CD pipelines	core, gitlab, book, marimo, tests, gitlab-book, gitlab-marimo, gitlab-tests

Declare a profile in .rhiza/template.yml:

repository: Jebel-Quant/rhiza
ref: v0.14.0

profiles:
  - github-project

Note: Profiles expand to their constituent bundles including all transitive requirements.

You can combine a profile with additional bundles:

profiles:
  - github-project
templates:
  - docker
  - github-docker

Available Template Bundles

Bundles are the atomic building blocks. Feature bundles are local-first — they do not include hosted workflow files. Platform overlay bundles (prefixed github- or gitlab-) add the CI/CD workflows for a given feature.

Any bundle can be selected on its own — its dependencies are resolved and installed automatically. The Auto-installs column