Skip to content

Contributing to kac

This repository is not open to contributions of code. Raise an issue instead: a bug, a contradiction, a question or a correction of fact. A pull request opened without a prior conversation is closed unmerged. Every change, the maintainer's included, is merged into main through a pull request that passes the validate check.

gh issue create --repo paul80nd/knowledge-as-code   # raise the bug, contradiction or question first

.github/CONTRIBUTING.md says why the repository works this way. To change kac without waiting on anybody, read Forking kac.

This page is about changing kac and this repository. Contributing knowledge covers adding a record (one Markdown document) to a corpus (one repository of records).

What an issue is for

An issue is welcome for any of these:

  • A bug in kac.
  • A rule that contradicts another, or fails on a real corpus.
  • A question about the taxonomy, the update model, or why something has its shape.
  • A page that says something the tool does not do.

What a pull request owes

Branch off main. A push to main is rejected. Before you open the pull request:

  1. Fix every page your change made wrong. A change to a command usually changes its page under docs/use/cli/.
  2. Where kac changed, add an entry under ## Unreleased in tooling/kac/CHANGELOG.md.
  3. Leave <Version> alone. Moving it publishes a release, and that is the owner's decision.
  4. Where a corpus's own records or schema change what it exports, or its plugin bundle includes a skill, a hook or a manifest you changed, move content-version in that corpus's .corpus.yaml. Where that corpus has consumers, move their resolved: lock and their own content-version in the same pull request. A change to kac moves no content-version, even where the exported bytes change. std-VERS states the rule.
  5. Run the test layers your change touches.
  6. Put a change of behaviour in a commit of its own.

The commit subject says what changed. The body and the pull request description say why, and list each test layer you ran with its result.

The checks that gate a merge

kac.yml runs on every pull request into main. Its validate job waits for every other job, and the branch rule requires validate.

Job What it runs
corpora validate, generate --check, update --check, export and pack in each corpus
tool The template's own checks, the unit, feature and golden layers, and a corpus created by the packed tool
lint yamllint --strict, actionlint and zizmor
docs zensical build, which fails on a dead link or a dead anchor
round-trip claude plugin validate on each corpus's plugin, then round-trip.sh on all but dog-fooding
import-round-trip tooling/tests/import-round-trip.sh, on Linux and Windows

round-trip runs every corpus on Linux and payments on Windows as well. A job missing from the validate job's needs: still runs but blocks nothing. WorkflowGateTests fails one.

Where to go next

How kac is put together shows where a change to kac goes.