Skip to content
This repository was archived by the owner on Oct 21, 2026. It is now read-only.

CONTRIBUTING.md

Latest commit

 

History

History
176 lines (133 loc) · 6.66 KB

CONTRIBUTING.md

File metadata and controls

176 lines (133 loc) · 6.66 KB
Raw

Contributing to kin-editor

Thanks for your interest in kin-editor. This guide covers local development, the conventions this repository follows, and how to get changes reviewed.

Development Setup

kin-editor is a TypeScript VS Code extension. You need Node.js (v18+) and npm:

npm install
npm run compile

Before opening a pull request, make sure the standard checks pass:

npm run lint
npm test
npm run compile

To package a local build:

npm run package:vsix

DCO Sign-Off

This project uses the Developer Certificate of Origin (DCO). Every commit you push on a pull request must carry a Signed-off-by trailer:

Signed-off-by: Your Name <you@example.com>

Add it by passing -s to git commit:

git commit -s -m "feat(explorer): add entity kind filter"

If you forgot to sign off earlier commits on your branch:

git commit -s --amend              # amend only the last commit
git rebase --signoff HEAD~N        # add sign-off to the last N commits

By signing off you certify that you wrote the code (or have the right to submit it) and that it may be distributed under the Apache License 2.0 that governs this repository. Bot-authored commits (Dependabot, GitHub Actions) are exempt.

AI-Assisted Contributions

Kin is built with significant AI assistance, and we welcome AI-assisted contributions from the community. A few requirements:

  • You are responsible for AI-generated code you submit. Review every line before opening a PR. If the model hallucinated an API call, an unsound block, or a security hole, that is your bug to catch.
  • AI-generated code is your contribution. By signing off your commits you assert that you have reviewed the generated code and are submitting it under your own name, not as a third-party work. Firelock asserts copyright over AI-generated code it produces; you assert copyright over what you produce and submit here.
  • No raw model output in commit messages or comments. Clean up generated prose before it lands in public history. Write durable, human-authored commit messages that describe the technical change.

Commit Messages

This repository uses Conventional Commits. Recent history shows the expected shape, a type(scope): summary subject:

feat(explorer): add entity kind filter to sidebar tree
fix(search): handle empty graph response gracefully
docs(readme): add marketplace install instructions

Common types are feat, fix, docs, test, refactor, perf, and chore. Scopes match the area you touched (explorer, search, trace, status, commands, and so on). Write the summary in the imperative mood and keep it focused on what changed and why.

Branch Naming and Commit Hygiene

Public Git history is part of the product, so keep it clean and reviewable:

  • Keep branch names topical, not tracker-coded. Prefer short, descriptive names like fix/search-empty-state or feat/entity-kind-filter. Avoid embedding internal issue or tracker IDs in a branch name. A squash merge copies the branch name into the public commit subject, so anything in the branch name lands in history verbatim.
  • Keep private context private. Do not publish private session URLs or IDs, secrets, or internal-only tracker references. Put non-sensitive technical context in the pull request.
  • Preserve provenance. Tool-specific attribution is optional and is not required. Hooks must not add, remove, or rewrite it, or rewrite authors, committers, timestamps, or history.
  • Use hooks only for validation. Hooks may reject private references or secrets, but they must not mutate commit metadata or history. Do not skip configured validation with --no-verify.

Pull Requests

  • Keep PRs scoped. Stage only the files your change actually needs. Unrelated cleanups belong in their own PR. That keeps review focused and history bisectable.
  • Make sure npm run lint, npm test, and npm run compile all pass.
  • If your change is user-facing, briefly describe it in the PR body so reviewers understand the before/after behavior.

Releases

Do not bump the extension version or create release tags in an ordinary pull request. After a release-impacting change reaches main, the protected release train opens or updates one generated release PR, selects a patch by default, and merges it only after the normal required checks pass. When a larger SemVer change is intentional, end the product PR body with exactly one immutable trailer:

Kin-Release-Intent: minor

Use major for a major release. The repository preserves the PR body in its squash commit and disables merge-commit and rebase methods, so this trailer is always part of landed first-parent evidence. The train scans those immutable commit messages since the last tag. Mutable PR and release-train labels are descriptive metadata only and cannot select or downgrade automatic release intent.

The resulting reviewed main commit is tagged automatically and published to the Visual Studio Marketplace, Open VSX, and GitHub Releases. The tag binds to the exact checked first-parent commit that introduced the prepared version; later main drift stays in the next release train. Failed generated-PR checks are classified and recovered before the controller may coalesce main or rewrite that exact release-PR head. They receive two bounded automatic reruns before one exact-head terminal issue is opened. A PR whose checks do not start receives one bounded activation commit; a second activation state is terminal instead of creating another head. Version tags are immutable. If a published build is bad, recover with a fixed higher version; do not move or replace the existing tag.

Reporting Issues

File issues on firelock-ai/kin-editor using the provided templates:

  • Bug reports. Use the bug report template.
  • Feature requests. Use the feature request template.

For security vulnerabilities, do not open a public issue. Follow the private reporting process in SECURITY.md.

Repository Boundaries

kin-editor is one repository within a larger ecosystem. Semantic graph storage and retrieval internals live in kin-db; the system of record CLI and daemon live in kin. If your change targets one of those concerns, open it against the repository that owns the code.

License

By contributing, you agree that your contributions are licensed under the Apache License 2.0, the license that covers this repository.

Code of Conduct

This project follows the Contributor Covenant. By participating, you are expected to uphold it.