Contributing on Katalyst Documentation

How to contribute

Mon, 01 Jan 0001 00:00:00 +0000

How to contribute#

Katalyst is an experimental, in-the-open project. Issues, feedback, and pull requests are all welcome. This page covers getting set up and shipping a change; for the project’s planning and documentation process, see How we plan and How we document.

Ground rules#

Be respectful. This project follows a Code of Conduct.
Open an issue to discuss substantial changes before investing in a large PR.
Keep changes focused; smaller PRs are easier to review and merge.

Where feedback goes#

Put feedback in public artifacts so it stays searchable and actionable:

How we document

Mon, 01 Jan 0001 00:00:00 +0000

How we document#

Like most knowledge bases, Katalyst’s documentation must balance two objectives:

Users, agents, and contributors can easily find what they need.
Content is comprehensive, has no internal contradictions, and is always up to date.

We do this by dividing documentation across four areas, each with a specific purpose.

Published documentation (Hugo): everything users and agents need to understand and use Katalyst - tutorials, how-to, reference, and deep-dives explaining the reasoning behind them.
Go doc comments: code-level API and design detail, co-located with the code
AGENTS.md files: conventions, required patterns, and gotchas for writing code in the repo, plus a pointer to each subsystem’s architecture deep-dive - a lean root file plus per-package files.
Specs and plans: product/ staging for in-flight ideas; each is deleted once its durable content graduates into the homes above.

By clearly delineating when and where to update documentation, this approach lets us minimize duplication and the risk of content drift, while still serving a wide variety of needs. That said, some overlap in content is unavoidable. Some judgement calls about what information belongs where will always be necessary. Making these judgement calls is up to the project maintainers.

How we test

Mon, 01 Jan 0001 00:00:00 +0000

How we test#

Katalyst follows TDD: new behavior arrives with a failing test first. Two traits shape the suite beyond that. Tests are the source of truth, and many of our docs are generated from them: the reference pages come from the check and inspector registries, and the worked examples come from the example registry, so a green suite keeps behavior and its documentation honest at once. And we test at seams, the named interfaces a katalyst run flows through, with a small set of styles that interlock into end-to-end coverage.

How we plan

Mon, 01 Jan 0001 00:00:00 +0000

How we plan#

How we use specs and plans to design, build, and document changes.

Two doc types#

Spec: what and why: the problem, the design, domain-model and architecture impact, open questions. A spec is a design doc in product/specs/{slug}-spec.md.
Plan: how: the step-by-step implementation, broken into phases, that references its spec ({slug}-plan.md). A spec can exist without a plan; a plan always references a spec.

For small, well-understood changes, skip the ceremony: a GitHub issue capturing the decision is often enough. Don’t write a full spec when an issue will do.

Code of conduct

Mon, 01 Jan 0001 00:00:00 +0000

Code of Conduct#

This project has adopted the Contributor Covenant, version 2.1, as its Code of Conduct. The full text is available at:

https://www.contributor-covenant.org/version/2/1/code_of_conduct/

In short: we are committed to providing a welcoming, harassment-free experience for everyone, and we expect all participants to act professionally and respectfully in all project spaces.

Reporting#

If you experience or witness unacceptable behavior, please report it to the project maintainer at abegong@gmail.com. All reports will be reviewed and handled confidentially.

Security policy

Mon, 01 Jan 0001 00:00:00 +0000

Security Policy#

Supported versions#

Katalyst is pre-1.0 and evolving quickly. Security fixes are applied to the latest release and main only.

Reporting a vulnerability#

Please do not open a public issue for security vulnerabilities.

Instead, report privately using GitHub’s private vulnerability reporting (Security → Advisories → “Report a vulnerability”). If that is unavailable, email abegong@gmail.com with details.