Thank you for helping improve Kollect.
This project follows the Code of Conduct and is governed per GOVERNANCE.md.
Pull requests must meet the linked standards before merge. Each document owns one concern — do not duplicate prose across them.
| Document | Owns |
|---|---|
| REQUIREMENTS.md | Product what — functional requirements and NFR targets |
| Engineering guidelines | Operator how well — error taxonomy, robustness, security model, perf, definition of done |
| Coding standards | Go how — lint, formatting, modules, race detector, CI gates |
| Testing strategy | Test pyramid (L0–L5), coverage floors, integration/e2e tiers |
| Spec workflow | How behavioural changes are specified, verified and closed (OpenSpec) |
| CONTRIBUTING.md | Process — commits, PR workflow, changelog, doc PR checklist |
| CODE_OF_CONDUCT.md | Community behavior standards (Contributor Covenant v2.1) |
| GOVERNANCE.md | Roles, decision making, continuity, security contact |
| SECURITY.md | Vulnerability reporting and threat model |
| Assurance case | Security claims, trust boundaries, countermeasures |
| Security review | Dated self-review findings and residual risks |
| SCA remediation policy | Dependency CVE and license remediation thresholds (OSPS-VM-05.01) |
| Architecture decision records | Locked design decisions — update or add ADRs for non-trivial changes |
| ADR and RFC process | When to write ADRs vs RFCs, numbering, lifecycle, review checklist |
| Planned features | Backlog and Exploring specs before they land on the phased roadmap |
| tooling-setup.md | Maintainer setup for arch-lint, depguard, SonarCloud |
| AGENTS.md | Instructions for AI coding assistants — commands, CI gates, change checklists |
Merge policy: use Rebase and merge on pull requests (see
Changelog and releases). main requires green preflight and
test CI checks and linear history.
Local preflight (before opening a PR): task check — the full local gate, one command: it
runs everything CI requires that can run locally (verify, lint, unit tests, vulncheck, scrub,
the shell and markdown lints, spec validation, gitleaks, the helm and RBAC audits, the build,
the workflow-security audit and every hack/test guard in every mode) and prints the
Docker/kind-dependent gates it leaves out, each with its reason (task test-integration,
task docker:build and the e2e-smoke scenarios stay separate). Individually:
task lint · task coverage · task coverage:race (recommended) · task verify · task scrub · gitleaks protect --staged --no-banner. Technical gate
details: coding-standards.md § Pull request and CI gates.
We follow Conventional Commits per
qoomon's cheatsheet, with an
optional gitmoji shortcode prefix (e.g. :sparkles:, not Unicode
emoji). Use shortcodes when they help scan history; omit them when they add noise.
Format:
:gitmoji: <type>(<optional scope>): <description>
<optional body>
<optional footer>
Types — pick the first matching category (do not misuse feat for pure docs/ci):
| Type | When to use |
|---|---|
feat |
Add, adjust, or remove a user-facing feature — CRDs, webhooks, operator behavior |
fix |
Fix a bug in API/UI behavior |
refactor |
Restructure code without changing API or UI behavior |
perf |
Performance improvement |
style |
Formatting, whitespace, lint-only — no behavior change |
test |
Add or correct tests |
docs |
Documentation only — CR references, README, ADRs |
build |
Build tools, dependencies, Dockerfile, version bumps |
ci |
CI/CD pipelines, GitHub Actions, deployment scripts |
chore |
Maintenance — .gitignore, scaffolding, non-user-facing tooling |
Scopes — optional, lowercase, ≤ 20 chars: api, controller, collect, sink,
helm, webhook, validation, transport, docs, ci, build. Do not use issue IDs as
scopes (reference issues in the footer or description instead).
Description — imperative present tense ("add" not "added"); lowercase first letter; no trailing period; ≤ ~72 chars on the subject line (after gitmoji + type/scope).
Breaking changes — pre-v0.x default is no breaking marker; CRD/schema pivots use plain
feat(api):. Mark a breaking change with feat(scope)!: / fix(scope)!: and a
BREAKING CHANGE: <migration note> footer, both on the commit, only when a
tagged release already exists and adopters must migrate. Do not mark breaking for pre-beta CRD churn,
internal refactors, or dev-only flag removal. Put the ! on the commit title, not only the PR
title or body: PRs are rebase-merged, so git-cliff never sees the PR, and the breaking-marker
check fails a PR whose title has ! or whose body has a BREAKING CHANGE: footer when no commit
title has !.
Examples (good):
:sparkles: feat(api): make KollectSink namespaced
:bug: fix(controller): set Degraded when export payload exceeds cap
:recycle: refactor(controller): extract scope check helper
:page_facing_up: docs: expand KollectProfile CR reference
:construction_worker: ci: fix e2e-nightly upload-artifact pin
Examples (avoid):
Feat(api): Added sink.
feat(api)!: change sink scope
feat: misc fixes
Capitalized or past-tense subjects, trailing periods, ! without a BREAKING CHANGE: footer,
and vague subjects.
CHANGELOG.md is generated from git history with
git-cliff (hack/release/cliff.toml); gitmoji tokens are stripped from changelog
headings automatically.
| Task | Purpose |
|---|---|
task changelog |
Preview the Unreleased section |
task changelog:write |
Regenerate full CHANGELOG.md |
task changelog:release |
Print notes for the latest tag |
task changelog:verify |
Fail if CHANGELOG.md is stale (local pre-tag check; not a PR gate) |
task helm-docs |
Regenerate charts/kollect/README.md from values.yaml |
task helm-docs:verify |
Fail if chart README is stale (CI helm job via task helm-test) |
task release-dry-run |
Build dist/ assets without pushing |
Only feat, fix, perf, refactor, and breaking commits appear in the user-facing changelog;
docs, test, chore, ci, build, and style are skipped (hack/release/cliff.toml).
Maintainer release flow — full runbook: docs/RELEASE.md. Summary:
- Merge work on
mainwith conventional commits.
GitHub merge policy: use Rebase and merge on pull requests; the protect-main ruleset allows no other method (squash and merge commits are disabled). main is protected by that ruleset: changes land through pull requests with required status checks, and force pushes and branch deletion are blocked. Direct pushes to main are blocked for every person, admins included. The ruleset has two bypass actors: the repository admin role, only when merging a pull request (the maintainer's RENOVATE_TOKEN carries it, so the self-hosted Renovate can merge digest-only bot PRs), and the changelog-sync App, which pushes the CHANGELOG.md commit after a merge.
2. task changelog — sanity-check grouping.
3. Bump charts/kollect/Chart.yaml version and appVersion, run task helm-docs, and update the
release-truth pages; land that prep commit through a PR. Do not hand-write a ## [X.Y.Z]
changelog heading: changelog-sync writes it after the tag.
4. git tag vX.Y.Z && git push origin vX.Y.Z — CI publishes image and GitHub Release after two
release-environment approvals.
5. Prepend the hand-written upgrade notes to the GitHub Release.
Tagged releases (v*.*.*) trigger .github/workflows/release.yaml:
multi-arch images to ghcr.io/platformrelay/kollect and ghcr.io/platformrelay/kollect-pipeline, Trivy scan, cosign
signing, SPDX SBOMs, Helm chart (OCI), and GitHub Release assets (install.yaml, install-crds.yaml,
chart tarball, checksums).
By contributing, you certify the Developer Certificate of Origin (DCO) (version 1.1):
Developer Certificate of Origin
Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
Include a Signed-off-by line in every commit message when you are able:
:sparkles: feat(sink): add example validation
Signed-off-by: Your Name <your.email@example.com>
Git can append this automatically: git commit -s. The DCO is a statement of license on your
contribution; it complements the MIT license in LICENSE. A DCO bot is not required —
maintainers may ask you to amend commits if sign-off is missing on substantive contributions.
Open a GitHub Issue for bugs, regressions, and feature requests. Do not use issues for security vulnerabilities — email konrad.heimel@gmail.com per SECURITY.md.
Include: Kollect version or commit, Kubernetes version, minimal repro YAML or steps, expected vs actual behavior, and relevant operator logs (redact secrets).
Looking for a small, review-friendly change? Try one of these:
| Area | Ideas |
|---|---|
| Docs | Fix typos, clarify Install Kollect, improve admonitions on procedural pages |
| ADRs | Typo or link fixes in docs/adr/ |
| Golden tests | Add or extend extractor golden fixtures under test/ |
| Markdown lint | Run task lint:markdown and fix warnings |
| Sample YAML | Improve config/samples/ or docs/examples/ manifests |
| UI | Small accessibility or copy fixes in ui/src/ (keep PRs focused) |
Search issues labeled
good first issue.
If none exist, pick a row above and mention it in your PR description.
All pull requests need green CI and maintainer approval before merge to main.
| Check | Task / workflow |
|---|---|
| Lint and format | task lint, task format:check (CI) |
| Tests and coverage floor | task coverage (CI) |
| Integration (when sink/backend touched) | task test-integration (Docker; fails unless every integration test ran and passed, as in CI; a new integration-tagged package must be added to INTEGRATION_PACKAGES in Taskfile.yml). Without Docker, task test-integration:explore reports what it could not run |
| Codegen drift | task verify (preflight) |
| Changelog drift | Not a PR gate: the changelog-sync workflow regenerates CHANGELOG.md after each merge; run task changelog:verify locally before tagging |
| Secret scan | gitleaks (CI) |
Reviewers (currently the maintainer only) verify:
- CI is green and local preflight steps were run
- Tests cover behavior changes; ADRs updated for architectural decisions
- No secrets, private strings, or forbidden identities (
task scrub, gitleaks) - User-facing changes have conventional commits suitable for the changelog
- Security-sensitive paths follow ADR-0104
External contributions always require maintainer review before merge. Maintainer-authored changes may merge without a second human reviewer today (solo-maintainer policy — see GOVERNANCE.md and ADR-0705).
- Fork or branch from
main. - Run the local preflight checklist (
task lint·task coverage·task coverage:race·task verify·task scrub). - Keep changes focused; update ADRs in
docs/adr/when making architectural decisions. - Ensure CI is green (
preflight+CIworkflows). - Request review; address feedback with additional commits (avoid force-push to
main).
For test pyramid tiers, coverage floors, and integration expectations see Testing strategy. For Go conventions and CI gate matrix see Coding standards.
User-facing docs live under docs/ and publish via MkDocs Material (ADR-0701).
When you change behavior or add features, update the matching pages and mkdocs.yml nav.
Use MkDocs Material admonitions (!!! type "Title") on procedural pages (Getting Started, Operator
Manual, examples):
| Type | Use for |
|---|---|
tip |
Shortcuts, optional paths, assumptions at page top |
note |
Context, why a flag exists, version caveats |
warning |
Data loss, security, pre-beta API, destructive steps |
info |
Maturity, scope, links to ADR decisions |
Placement: one tip or note at the top of Getting Started / Operator Manual pages (link to
Understand the basics); warning before mutating shell blocks when
security-sensitive; note after complex YAML pointing to CR field reference. Pre-beta features get
warning with a ROADMAP link. Aim for 2–4 admonitions per page unless
troubleshooting tables need more.
Tabs (optional, for install variants):
=== "Helm"
```sh
helm install kollect charts/kollect ...
```
=== "kind"
```sh
task kind-dev-up
```- New feature → update ROADMAP status and planned features when backlog-facing
- Architectural decision → ADR or RFC per ADR/RFC process (
docs/adr/README.md,mkdocs.ymlnav) - New CR field →
docs/crds/*.mdand CR reference - New label/annotation → ANNOTATIONS-LABELS and relevant CR page
- Add or move pages in
mkdocs.ymlnav - At least one admonition on new procedural pages
- Run
task lint:markdownandmkdocs buildbefore opening a PR
Glossary CRD section: regenerate with python3 hack/gen-glossary.py after schema description changes.
charts/kollect/README.md is generated from values.yaml comments and
README.md.gotmpl via helm-docs.
- Document values with
# -- descriptioncomments invalues.yaml. - Edit narrative sections in
README.md.gotmpl(install recipes, fleet/multi-cluster, monitoring, auth). - Regenerate:
task helm-docs— CI enforces drift viatask helm-docs:verifyin thehelmjob (task helm-test).
By contributing, you agree that your contributions are licensed under the project MIT license and that you certify the DCO as described above.
All participants are expected to follow the Code of Conduct.