Skip to content

Latest commit

 

History

History
176 lines (140 loc) · 9.87 KB

CONTRIBUTING.md

File metadata and controls

176 lines (140 loc) · 9.87 KB

Contributing

These rules apply equally to humans and AI agents.

Contribution license

Unless separately agreed in writing, contributions to Nocterm are submitted under the PolyForm Perimeter License 1.0.1. By submitting a contribution, you confirm that you have the right to license it under these terms.

Contributions to the third-party forks under vendor/, including local patches, are instead submitted under the license declared by the corresponding vendored package: Apache-2.0 for alacritty_terminal, gpui-base and gpui-component, and MIT for tid-rs. Preserve upstream copyright notices and license files, and mark changed Apache-2.0 files prominently. This policy applies to new contributions; it does not change the license of code submitted by others under different terms.

Setup

scripts/setup.sh   # enables the commit-msg hook

Branching

master is the release branch and is only changed through pull requests. dev is the integration branch for work being validated before release.

  • Choose and record the PR target before branching: master for release-ready changes, dev for integration work. Branch from that target and name the branch <type>/<short-kebab-description>: feat/tab-completion, fix/resize-crash.
  • Keep branches short-lived and PRs small — one logical change each.
  • Changes integrated into dev reach master through a release-ready PR from dev. Ordinary PRs into master are squash-merged: the title becomes the commit on master, so it must be a valid commit message. Ordinary integration PRs into dev may use merge commits. If a PR contains both vendor/ and crates/ or src/ changes, keep them in separate commits and rebase-merge the PR to preserve that separation. This also applies when promoting such history from dev to master: neither squash nor a merge commit may combine the changes. Correlated commits may need each other to pass checks; the final reviewed PR head must pass all required checks. Titles and non-merge commits follow Conventional Commits. CI checks the actual before/head history on pushes to dev and master, including commits created by GitHub; this detects invalid landings after they occur. Require CI passed in branch protection and choose the prescribed merge method before landing.
  • No force-pushes to master, no merge commits on master.
  • Review against the recorded PR target, using its merge base with the feature branch; reviewing integration work against master includes unrelated changes.

Commit messages

Conventional Commits 1.0, enforced by the commit-msg hook and CI (scripts/lint-commit-msg.sh).

<type>(<scope>)!: <subject>

<body>

<footers>
Type Use for Release effect
feat user-visible capability minor
fix user-visible bug fix patch
perf performance improvement, no behaviour change patch
revert reverting an earlier commit patch
docs documentation only none
refactor restructuring, no behaviour change none
test tests only none
build build system, dependencies none
ci CI configuration none
style formatting, no logic change none
chore anything else that doesn't touch shipped code none

Rules:

  • Header ≤ 72 chars. Subject in imperative mood, lower-case first letter, no trailing period: fix(pty): handle zero-size resize.
  • Scope is optional, lower-case kebab, and names the affected crate directory (ssh, agent-runtime, connections-model). Use app for the root src/, deps for dependency bumps and xtask for tooling.
  • Body explains why, not what; wrap at ~100 chars. Blank line after the header.
  • Breaking changes: add ! after the type/scope and a BREAKING CHANGE: <what breaks and how to migrate> footer.
  • Footers: Refs: #123, Closes: #123, Co-Authored-By: ....
  • One logical change per commit. If the subject needs "and", split it.

Pick the type by what the user of the software sees, not by which files changed: a bug fix that only edits a test helper is test, a refactor that fixes a crash is fix.

Code size

A Rust source file may have at most 800 lines, tests included. cargo xtask architecture (run in CI) enforces this ceiling; it is not a target size. Keep files focused on one coherent responsibility. Separate independent responsibilities as they emerge, even below warning thresholds, into named child modules; move a large mod tests into foo/tests.rs. Stateful extractions own their state and transitions; pure logic can be a cohesive module of functions without an artificial owner type. Moving more methods of the same growing type into another file is not an extraction. Do not fragment a coherent module just to meet an arbitrary preferred line count. The legacy exception list xtask/oversized-files.toml is empty; never add an entry to make a check pass.

cargo xtask architecture warns, without failing, at about four fifths of each structural limit (640 lines, 12 fields, 4 implementation files). cargo xtask survey <package> shows the files, types and module references to design the split from; --type <Type> groups a struct's fields by the methods that use them together.

A function may have at most 80 lines and a cognitive complexity of 20 (clippy.toml). Functions that were already over carry #[expect(clippy::too_many_lines, reason = "...")]; once one is split, the unfulfilled expectation fails clippy, so remove the attribute. #[allow] for these lints is rejected by cargo xtask architecture. Do not add new complexity expectations; extract smaller functions instead. Architecture checks reject overrides and conditional bypasses for those lints. Existing expectations require reason = "predates the limit", and their count per package may only decrease. The exact inventory in xtask/baseline.toml also constrains large structs, implementation spread, public state, globals, shutdown hooks, string errors and domain I/O. Lower or remove entries when code improves; never regenerate or raise the inventory. See architecture guardrails.

Verification

During development, choose the smallest check that answers the current question: one regression test, one test target, a library or an affected package. Batch a coherent edit before checking it. Do not run a fixed build/lint/test/architecture bundle after every edit or extraction. A test compiles its target; running both cargo check and cargo build first is usually redundant.

At completion, follow the input-based completion matrix. Scoped changes use affected targets and consumers; broad shared changes or uncertain workspace impact need full workspace verification. Required CI is independent. Reuse valid results and rerun a failing check first; keep evidence tied to its source/configuration. The gate procedure provides examples. Documentation and script-only work use relevant links, script tests and configuration validators unless they affect Rust/generator inputs.

For changed hot paths, account for work per event, frequency and retained memory. Rendering and input callbacks consume prepared state; expensive work has bounded background execution. Cache repeated work only with clear keys, invalidation, bounds and lifecycle. Verify affected interaction and measure optimization claims with representative before/after workloads; see the performance procedure.

Cargo resources

Cargo keeps the caller's CARGO_BUILD_JOBS, Cargo configuration and normal defaults. Choose a local budget for the machine; no fixed job count is required. When parallel builds need coordination, the optional helper serializes commands:

.claude/hooks/cargo-serial.sh cargo test -p nocterm-ssh

Its default lock lives in the Git common directory, so linked worktrees share it and independent clones do not. NOCTERM_CARGO_LOCK=<path> selects another lock (use an absolute path to coordinate different working directories or repositories). NOCTERM_CARGO_LOCK=off runs without the helper lock. The helper needs flock when locking; if unavailable it fails promptly with instructions. Direct Cargo is supported on every platform and keeps Cargo's own target-directory locking.

For shared verification, coordinate one executor and avoid duplicate checks on the same inputs. Keep a stable target directory per worktree; do not touch all sources or clean caches to start another check. Investigate a concrete stale artifact first. Local resource settings may be supplied in the shell or personal configuration and do not belong in committed product rules.

Pull requests

Vendored forks have reproducible binary patches against checksum-pinned published archives. Run python3 scripts/test-vendor-patches.py and python3 scripts/check-vendor-patches.py for vendor changes; see vendor patch maintenance. Keep vendor updates in separate commits from application changes under crates/ or src/.

  • Title: Conventional Commit, as above.
  • Description: what, why, how it was verified.
  • CI must be green; at least one review (human or the reviewer agent plus human sign-off).

Releases

Fully automated from commit history — see docs/RELEASING.md. Never edit CHANGELOG.md, version.txt or tags by hand.