Skip to content

Contributing

Changes to Ireul propagate to every repo that upgrades its PLATFORM_VERSION. Treat every change as a breaking change candidate and version accordingly.

Change process

  1. Branch off main.
  2. Make changes to the relevant files.
  3. If a tool version changed, update both versions.yml and the matching additional_dependencies entry in .pre-commit-hooks.yaml.
  4. If the hook logic changed, verify that the scaffold mkdocs.yml still works against the updated hook.
  5. Open a PR. Do not merge directly to main.
  6. After merge, cut a semver tag.
  7. Update PLATFORM_VERSION in dependent repos via separate PRs.

Versioning rules

Ireul uses semantic versioning.

Change type Version bump Examples
New hook, new env var dial, new scaffold file Minor (v0.1.0 → v0.2.0) Adding hadolint hook, adding DOCS_LOGO_PATH dial
Tool version upgrade, hook logic fix, CSS update Patch (v0.1.0 → v0.1.1) ruff 0.4.4 → 0.4.5, hook palette handling fix
Removed hook, renamed env var, scaffold breaking change Major (v0.1.0 → v1.0.0) Dropping Python 3.11 support, renaming DOCS_CSS_URL

Cutting a release

# Tag the release commit with the new semver version and push the tag to GitHub
git tag v0.2.0
git push origin v0.2.0

The Cloudflare Pages deployment of mkdocs/stylesheets/platform.css happens on push to main, not on tag. CSS updates are live immediately after merge regardless of tag.

Notifying dependent repos

After cutting a tag, open a PR in each dependent repo to update:

  • PLATFORM_VERSION in .env and .env.example
  • rev: in .pre-commit-config.yaml
# Update the platform version pin and reinstall hooks to pull updated hook dependencies
pre-commit autoupdate

Note

pre-commit autoupdate will update rev: to the latest tag automatically if the repo is public. Verify it resolved to the intended tag before committing.

What not to change

  • Do not rename existing env var dials without a major version bump. Repos that set DOCS_CSS_URL in .env will silently stop working if the name changes.
  • Do not remove hook IDs. Repos that reference a hook ID that no longer exists will fail pre-commit install.
  • Do not change the CSS variable names (--magi-amber, etc.) in platform.css without auditing all repos for any local overrides that reference them.