Skip to content

Lesson 10 — Customising Safely

Rhiza manages a set of files in your project. This raises an obvious question: what if you need to change something that Rhiza controls? This lesson covers the right ways to customise a Rhiza-managed project without getting into conflicts when you update.

The core rule

If you edit a file that Rhiza manages, the next /rhiza:update will overwrite your change.

This is intentional. Template-managed files are meant to stay consistent with the template. The right response to needing a customisation is not to edit the file — it is to use one of the extension mechanisms described below.

Option 1: Use the Makefile extension hooks

The core bundle provides two files explicitly designed for local customisation:

  • custom-task.mk — add your own make targets here. This file is not managed by the template, so you can edit it freely.
  • custom-env.mk — set project-specific environment variables that Makefile targets will use.

Example: adding a custom make target to seed a local database.

# custom-task.mk

.PHONY: seed-db
seed-db:  ## Seed the local development database
    python scripts/seed_db.py

After adding this, make seed-db will work alongside all the standard Rhiza targets, and it will never be touched by an update.

Option 2: Exclude a file and own it locally

If you need to diverge significantly from a template file — for example, your project needs a custom CI workflow that is incompatible with the template's version — add the file to exclude: in .rhiza/template.yml:

exclude: |
  .github/workflows/rhiza_ci.yml

From that point on, /rhiza:update will never touch that file. You are responsible for maintaining it, including applying any relevant upstream changes manually.

Warning: Be deliberate here. Excluded files are excluded permanently until you remove them from the list. Security fixes in the template will not reach excluded files automatically.

Option 3: Fork the template for your organisation

This is the recommended approach for teams. Instead of pointing all your projects at Jebel-Quant/rhiza, you fork it into your own organisation:

Jebel-Quant/rhiza  →  your-org/rhiza

Your fork becomes your org's source of truth. You customise it to reflect your team's standards — different default Python version, additional CI steps, org-specific secrets, whatever you need. All your projects then point their repository: at your-org/rhiza.

When Jebel-Quant/rhiza releases a new version, you decide when and what to pull into your fork. You are in control of what flows downstream.

# .rhiza/template.yml in a project from your org
repository: your-org/rhiza
ref: v1.2.0

This pattern scales well: one place to manage standards, automated propagation to all consuming repos, and full control over what gets adopted and when.

What you should never do

Don't edit template-managed files directly unless you also add them to exclude:. You will lose your changes the next time you run /rhiza:update.

Don't work around updates to avoid dealing with PRs. The /rhiza:update PR is the system working correctly. If an update surfaces too many changes you don't want, the right answer is to use exclude: for files you own locally, not to stop updating.

Don't diverge silently. If you make a local change and do not exclude the file, the next /rhiza:update PR will show the revert of your change. This is confusing for reviewers. Be explicit: if you own a file, exclude it.

Summary of extension points

Need Mechanism
Custom make targets Edit custom-task.mk
Custom environment variables for make Edit custom-env.mk
Permanently own a specific file Add to exclude: in template.yml
Customise the template itself for your whole org Fork the template repo

Next: Lesson 11 — The Rhiza Ecosystem