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 template bundles by name — pre-configured sets of related files grouped by feature:

# .rhiza/template.yml
repository: Jebel-Quant/rhiza
ref: v0.7.1

templates:
  - core
  - tests
  - github
  - 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.7.1 or main)
• templates - Template bundles to include by name (see Available Template Bundles below)

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/scripts/customisations/*

💡 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 Template Bundles
• 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

📝 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: Use make adr to create a new ADR with AI assistance. The workflow will generate a comprehensive ADR document, update the index, and create 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 generation with pdoc and companion books
• 🔍 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

Available Template Bundles

Rhiza organises its templates into bundles — pre-configured sets of related files grouped by feature. Select the bundles you need in .rhiza/template.yml:

Bundle	Description	Requires	Standalone
core	Core Rhiza infrastructure (Makefile, linting, docs)	—	✅
github	GitHub Actions workflows for CI/CD	core	✅
tests	Testing infrastructure with pytest, coverage, and type checking	—	✅
marimo	Interactive Marimo notebooks for data exploration and documentation	—	✅
book	Comprehensive documentation book (API docs, coverage, notebooks)	tests	❌
docker	Docker containerization support	—	✅
devcontainer	VS Code DevContainer configuration	—	✅
gitlab	GitLab CI/CD pipeline configuration	core	✅
presentation	Presentation building using Marp	—	✅
lfs	Git LFS (Large File Storage) support	—	✅
legal	Legal and community files (LICENSE, CONTRIBUTING, CODE_OF_CONDUCT)	—	✅
renovate	Renovate bot configuration for automated dependency updates	—	✅
gh-aw	GitHub Agentic Workflows for AI-driven repository automation	github	✅

Tip: Bundles marked Standalone: ❌ cannot be used alone and must be combined with the bundles listed in the Requires column.

For a complete reference of every file included in each bundle, see .rhiza/template-bundles.yml.

🧩 Integration Guide

Rhiza provides reusable configuration templates that you can integrate into your existing Python projects.

Prerequisites

• Python 3.11+ - Ensure your project supports Python 3.11 or newer
• Git - Your project should be a Git repository
• Backup - Consider committing any uncommitted changes before integration

Automated Integration (Recommended)

The fastest way to integrate Rhiza:

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

# Initialise configuration templates
uvx rhiza init

# Edit .rhiza/template.yml to select desired templates
# Then sync the templates
uvx rhiza sync

Options:

• --branch <branch> - Use a specific rhiza branch (default: main)
• --help - Show detailed usage information

For a full step-by-step tutorial covering init, bundle selection, first materialise, and the sync lifecycle, see rhiza-education Lessons 6–8.

Automated Sync (Continuous Updates)

Keep your templates up-to-date with automated sync workflows:

• Configure .rhiza/template.yml to define which templates to include/exclude
• The .github/workflows/sync.yml workflow runs on schedule or manually
• Creates pull requests with template updates

For GitHub Token configuration and details, see the GitHub Actions documentation.

What to Expect After Integration

• Automated CI/CD - GitHub Actions workflows for testing, linting, and releases
• Code Quality Tools - Pre-commit hooks, ruff formatting, and pytest configuration
• Task Automation - Makefile with common development tasks
• Dev Container - Optional VS Code/Codespaces environment
• Documentation - Automated documentation generation

Troubleshooting Integration

• Makefile conflicts: Merge targets with existing build scripts
• Pre-commit failures: Run make fmt to fix formatting issues
• Workflow failures: Check Python version in .python-version and pyproject.toml
• Dev container issues: See .devcontainer/README.md

📋 Available Tasks

The project uses a Makefile as the primary entry point for all tasks, powered by uv for fast Python package management.

Key Commands

make install         # Install dependencies and setup environment
make test            # Run test suite with coverage
make fmt             # Format and lint code
make todos           # Scan for TODO/FIXME/HACK comments
make sync            # Sync with template repository
make release         # Create and publish a new release
make marimo          # Start Marimo notebook server
make book            # Build documentation

Run make help for a complete list of 40+ available targets.

Show all available targets

  ____  _     _
 |  _ \| |__ (_)______ _
 | |_) | '_ \| |_  / _\`|
 |  _ <| | | | |/ / (_| |
 |_| \_\_| |_|_/___\__,_|

Usage:
  make <target>

Targets:

Rhiza Workflows
  sync                  sync with template repository as defined in .rhiza/template.yml
  validate              validate project structure against template repository as defined in .rhiza/template.yml
  readme                update README.md with current Makefile help output

Bootstrap
  install-uv            ensure uv/uvx is installed
  install               install
  clean                 Clean project artifacts and stale local branches

Quality and Formatting
  deptry                Run deptry
  fmt                   check the pre-commit hooks and the linting

Releasing and Versioning
  bump                  bump version
  release               create tag and push to remote with prompts

Meta
  help                  Display this help message
  version-matrix        Emit the list of supported Python versions from pyproject.toml

Development and Testing
  test                  run all tests
  benchmark             run performance benchmarks

Documentation
  docs                  create documentation with pdoc
  book                  compile the companion book

Marimo Notebooks
  marimo-validate       validate all Marimo notebooks can run
  marimo                fire up Marimo server
  marimushka            export Marimo notebooks to HTML

Presentation
  presentation          generate presentation slides from PRESENTATION.md using Marp
  presentation-pdf      generate PDF presentation from PRESENTATION.md using Marp
  presentation-serve    serve presentation interactively with Marp

Docker
  docker-build          build Docker image 
  docker-run            run the Docker container
  docker-clean          remove Docker image

Agentic Workflows
  copilot               open interactive prompt for copilot
  analyse-repo          run the analyser agent to update REPOSITORY_ANALYSIS.md
  summarise-changes     summarise changes since the most recent release/tag
  install-copilot       checks for copilot and prompts to install

GitHub Helpers
  gh-install            check for gh cli existence and install extensions
  view-prs              list open pull requests
  view-issues           list open issues
  failed-workflows      list recent failing workflow runs
  whoami                check github auth status

Custom Tasks
  hello-rhiza           a custom greeting task
  post-install          run custom logic after core install

Note: The help output is automatically generated from the Makefile. When you modify Makefile targets, run make readme to update this section, or the pre-commit hook will update it automatically.

🎯 Advanced Topics

Marimo Notebooks

This project supports Marimo notebooks for interactive documentation and exploration.

make marimo  # Start Marimo server

For configuration details including dependency management and pythonpath setup, see the Marimo documentation.

Presentations

Generate presentation slides using Marp:

make presentation        # Generate HTML slides
make presentation-pdf    # Generate PDF slides
make presentation-serve  # Serve with live reload

For detailed information about creating and customising presentations, see presentation/README.md.

Documentation Examples

README code blocks can be tested when tests are configured.

# Example code block
import math
print("Hello, World!")
print(1 + 1)
print(round(math.pi, 2))
print(round(math.cos(math.pi/4.0), 2))

Hello, World!
2
3.14
0.71

Documentation Customisation

For information on customising the look and feel of your documentation, see book/README.md.

Python Version Management

The .python-version file specifies the default Python version for local development. Tools like uv and pyenv automatically use this version. Simply update this file to change your local Python version.

Makefile Customisation

Rhiza uses a modular Makefile system with extension points (hooks) for customisation. See .rhiza/make.d/README.md for the complete guide including:

• Extension points and hooks
• Custom target creation
• Module ordering conventions

Custom Build Scripts

For system dependencies and custom build steps, see docs/CUSTOMIZATION.md.

Private GitHub Packages

Rhiza's template workflows automatically support private GitHub packages from the same organization. Simply add them to your pyproject.toml:

In pyproject.toml:

[tool.uv.sources]
my-package = { git = "https://github.com/jebel-quant/my-package.git", rev = "v1.0.0" }

Git authentication is already configured in all Rhiza workflows (CI, book, release, etc.) using the default GITHUB_TOKEN, which automatically provides read access to repositories in the same organization.

For custom workflows or local development setup, see .rhiza/docs/PRIVATE_PACKAGES.md.

Release Management

For information on versioning, tagging, and publishing releases, see .rhiza/docs/RELEASING.md.

Dev Container

This repository includes a template Dev Container configuration for seamless development in VS Code and GitHub Codespaces. See .devcontainer/README.md for setup, configuration, and troubleshooting.

For details about the VS Code extensions configured in the Dev Container, see docs/VSCODE_EXTENSIONS.md.

🔄 CI/CD Support

GitHub Actions

The .github/ directory contains comprehensive GitHub Actions workflows for:

• CI testing across multiple Python versions
• Pre-commit checks and code quality
• Dependency checking with deptry
• Documentation building
• Docker and devcontainer validation
• Release automation
• Template synchronization

GitLab CI/CD

Rhiza provides GitLab CI/CD workflow configurations with feature parity to GitHub Actions. The .gitlab/ directory includes workflows for CI, validation, dependency checking, documentation, sync, and releases.

Quick setup:

cp -r .gitlab/ /path/to/your/project/
cp .gitlab-ci.yml /path/to/your/project/

For complete GitLab setup instructions, configuration variables, and troubleshooting, see .gitlab/README.md.

📋 Project Maintainability

Rhiza includes comprehensive maintainability features to help track project health and evolution:

Roadmap & Planning

• ROADMAP.md - Detailed project roadmap with planned features, release timeline, and long-term vision
• docs/PROJECT_BOARD.md - Guide for setting up GitHub Project Boards to track enhancements and roadmap items

Technical Debt Tracking

• docs/TECHNICAL_DEBT.md - Comprehensive tracking of known limitations, debt items, and future improvements
• make todos - Automated scanning for TODO, FIXME, and HACK comments across the codebase

Changelog Management

• docs/CHANGELOG_GUIDE.md - Guide for enhanced changelog generation with PR categorization
• .github/release.yml - Automated PR categorization for release notes

Run make todos to scan for technical debt markers in your codebase, or explore the roadmap and technical debt documents to understand project evolution and planned improvements.

📖 Learning Resources

For a structured, tutorial-style introduction to Rhiza — covering CI/CD concepts, uv, Python project conventions, the sync lifecycle, and the full Rhiza ecosystem — see the companion education repository:

jebel-quant/rhiza-education · Rendered site

The curriculum walks you through twelve lessons in order, from the motivation for living templates all the way to running your first sync, configuring Renovate, and customising safely.

🛠️ Contributing to Rhiza

Contributions are welcome! To contribute to Rhiza itself (not using Rhiza in your project):

1. Fork the repository
2. Clone and setup:

   git clone https://github.com/your-username/rhiza.git
   cd rhiza
   make install

3. Create your feature branch (git checkout -b feature/amazing-feature)
4. Make your changes and test (make test && make fmt)
5. Commit your changes (git commit -m 'Add some amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• GitHub Actions - For CI/CD capabilities
• Marimo - For interactive notebooks
• UV - For fast Python package operations
• Ruff - For Python linting and formatting
• Marp - For presentation generation