Skip to content

workflow

Jump to bottom
github-actions[bot] edited this page May 6, 2026 · 1 revision

Workflow & Governance

This page documents how the team works in this repository.

Branch Policy

main is the only long-term branch. Feature branches are short-lived — open a PR, get it merged, delete the branch.

Contribution Flow

1. Create a branch

git checkout main
git pull --ff-only
git checkout -b feature/your-change

Accepted prefixes (enforced by CI):

  • feature/*
  • fix/*
  • chore/*
  • docs/*
  • refactor/*
  • test/*
  • hotfix/*
  • dependabot/*

2. Make changes

  • Keep commits focused and signed (GPG signing is required)
  • Run ruff check src tests and pytest tests -q before pushing
  • Update docs when behavior or architecture changes

3. Open a PR to main 

git push origin feature/your-change

Open a PR, wait for CI, get a review approval from @kleinpanic (required by CODEOWNERS for all files; .github/workflows/, README.md, and docs/** are additionally gated).

Merge Convention

PRs are squash-merged to keep a linear history. Merge commits and rebase merges are not used. Resolve all conversations before merging.

CI Jobs

Every PR and push to main runs the following jobs:

Workflow Jobs
ci.yml Test, Coverage, Python Compat (3.11 / 3.12 / 3.13), Dead Code Analysis
quick-checks.yml Ruff Lint, Ruff Format, Mypy Type Check
branch-policy.yml Branch Name Policy
security.yml CodeQL Analyze, Dependency Review

Dead Code Analysis and Mypy are non-blocking (warnings only). Coverage threshold is 80%; add no-coverage-check to the PR body to bypass when justified.

AI and Automation Policy

No AI auto-fix or auto-doc workflows run in the merge path.

  • Fix CI failures intentionally.
  • Review all generated output before merging it.
  • Documentation updates go through normal PR review.

Docs Site

The public docs site is built with MkDocs Material from docs-site/ and deployed to GitHub Pages on every push to main via pages.yml. The deploy pre-fetches live Canvas data into static JSON and installs the agent demo page and extension source.

When updating docs:

  • Edit docs-site/ for site-facing pages
  • Edit README.md for repo-facing overview changes
  • Keep roadmap, workflow, and architecture pages in sync with actual behavior

Quick Reference

Action Path
Feature work short-lived branch → PR → squash merge
Docs update docs-site/ + README.md when needed
Governance change update GitHub settings and document it here
Architecture change update code + docs-site/architecture.md

Clone this wiki locally