Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
161 lines (112 loc) · 6.25 KB

CONTRIBUTING.md

File metadata and controls

161 lines (112 loc) · 6.25 KB
Raw

Contributing to KnightCode

This guide exists to save both sides time.

Philosophy

First things first: KnightCode's core is minimal.

The whole point of this project is a small request. The system prompt and tool definitions sit at a measured floor of roughly 1,100 tokens; every byte added to the core is paid for on every request, by every user, forever.

If your feature does not belong in the core, it should be an extension or a skill. PRs that bloat the core will likely be rejected. Even hook points for extensions should be well considered and discussed, to avoid adding unmaintainable bloat and complex interactions.

The One Rule

You must understand your code. If you cannot explain what your changes do and how they interact with the rest of the system, your PR will be closed.

Using AI to write code is fine. Submitting AI-generated slop without understanding it is not.

If you use an agent, run it from the repository root so it picks up AGENTS.md automatically. Your agent must follow the rules and guidelines in that file.

Contribution Gate

All issues and PRs from new contributors are auto-closed by default.

Issues submitted Friday through Sunday are not guaranteed to be reviewed.

Maintainers review auto-closed issues daily and reopen worthwhile ones. Issues that do not meet the quality bar below will not be reopened or receive a reply.

Approval happens through maintainer replies on issues:

  • lgtmi: your future issues will not be auto-closed
  • lgtm: your future issues and PRs will not be auto-closed

The command must be at the start of the reply (optionally after one or more @username mentions) or at the end. lgtmi does not grant rights to submit PRs. Only lgtm grants rights to submit PRs.

Quality Bar For Issues

If you open an issue, you must use one of the GitHub issue templates.

If you open an issue, keep it short, concrete, and worth reading.

  • Keep it concise. If it does not fit on one screen, it is too long.
  • Write in your own voice (do not use an LLM to generate text; if you must, follow up with a clearly AI-labeled comment).
  • State the bug or request clearly.
  • Explain why it matters.
  • Include the output of knightcode --version, your platform, and the provider and model you were using.
  • If you want to implement the change yourself, say so.

If the issue is real and written well, a maintainer may reopen it or reply with lgtmi or lgtm in the command position described above.

Blocking

If you ignore this document twice, or if you spam the tracker with agent-generated issues, your GitHub account will be permanently blocked.

If you send a large volume of issues through automation, your GitHub account will be permanently blocked. No taksies backsies.

Before Submitting a PR

Do not open a PR unless you have already been approved by a maintainer using lgtm in the command position described above.

Before submitting a PR:

bun install
bun run check-types
bun run test

Both must pass. They do not cover the desktop app, which has its own: for a change under apps/desktop, also run bun run check-types and bun run test from that folder. CI runs all of these, a binary build and smoke test, and the desktop app's packaging and end-to-end tests; see .github/workflows/ci.yml.

Do not edit CHANGELOG.md by hand. Changelogs are generated by Changesets. If your change is user-visible, add a changeset instead:

bun run changeset [category] [bump] [cli|desktop]   # defaults: fixed patch cli

That writes .changeset/<your-branch>.md, already filled in for @knightcodeai/cli (or @knightcode/desktop with desktop), and you finish the sentence:

Fixed Windows shell aborts crashing KnightCode when taskkill.exe is missing.

The first word is the category — Added, Changed, Deprecated, Removed, Fixed or Security — and it groups the entry under the matching heading in the released changelog. Keep it as the first word of the sentence; the rest is copied verbatim. CI rejects an entry that starts with anything else, so the miscategorised entry never reaches a release.

One changeset per change: an entry that describes two things has to be filed under one heading, and one of them ends up in the wrong place. Two changes in a branch means two changesets — run the command again and it takes the next free -2 suffix.

Check it before pushing, the same way CI does:

bun run scripts/changelog-sections.ts

A change to the desktop app (apps/desktop) takes a desktop changeset, which lands in apps/desktop/CHANGELOG.md and the desktop release's notes. Its app server side (packages/cli, packages/app-server-protocol) is part of the CLI, so a change to both takes one of each. No other package takes a changeset: they are private and never versioned, and CI refuses a changeset that names one.

Commit the generated file in .changeset/ with your PR. The release workflow turns accumulated changesets into a "Version Packages" PR. Merging it publishes the CLI to npm when it gave the CLI a new version, and sets the desktop app's next version, which the desktop release workflow builds when it is run; a Version PR with only desktop changesets publishes nothing to npm.

If you are adding a new provider to packages/ai, see AGENTS.md for the required tests.

Questions?

Ask in Discussions.

FAQ

Why are new issues and PRs auto-closed?

Auto-closing creates a buffer so maintainers can review the tracker on their own schedule and reopen the issues that meet the quality bar. Many reports do not meet that bar, or are slung at the repository mindlessly via an agent instead of being reviewed and shaped by the person submitting them.

Why do some issues get no reply?

A reply is maintenance work too. Low-signal issues, unclear reports, duplicates, and issues that do not follow this guide may be closed without discussion. This keeps time available for reproducible bugs, thoughtful requests, and contributors who have done the work to make their report actionable.

Is this hostile to contributors?

No. It is a guardrail against burnout and tracker spam. Short, concrete, reproducible issues are welcome. Thoughtful contributions are welcome. Automated slop, entitlement, and large volumes of low-effort reports are not.