diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 0000000..741b3d0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,62 @@ +name: Bug report +description: Something renders wrong, behaves wrong, or crashes. +labels: [bug] +body: + - type: markdown + attributes: + value: | + `tread` is a terminal program, so the terminal matters as much as the OS. + Those two fields are usually what makes a report reproducible. + + - type: textarea + id: what + attributes: + label: What happened + description: What you did, what you expected, what you got instead. + validations: + required: true + + - type: input + id: version + attributes: + label: Version + description: Output of `tread --version`. + placeholder: tread 0.2.0 + validations: + required: true + + - type: input + id: terminal + attributes: + label: Terminal + description: > + Which terminal emulator, and its version if you know it. On Windows, + Windows Terminal and conhost behave differently and it matters. + placeholder: Windows Terminal 1.21 / iTerm2 3.5 / xterm / VS Code + validations: + required: true + + - type: input + id: os + attributes: + label: OS and architecture + placeholder: Windows 11 arm64 / macOS 15 Apple Silicon / Ubuntu 24.04 x86_64 + validations: + required: true + + - type: textarea + id: file + attributes: + label: A file that reproduces it + description: > + The smallest markdown/CSV/JSON that shows the problem, pasted or + attached. For a rendering bug this is usually the whole report. + render: text + + - type: textarea + id: extra + attributes: + label: Anything else + description: > + `--plain --width 80` output is often useful, since it shows the render + without the terminal in the way. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..0086358 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: true diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml new file mode 100644 index 0000000..e12b340 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature.yml @@ -0,0 +1,26 @@ +name: Feature or format request +description: Something tread should be able to read or do. +labels: [enhancement] +body: + - type: markdown + attributes: + value: | + Please check `CONTRIBUTING.md` first — a few things are settled and will + be declined regardless of implementation, notably adding a dependency + and capturing the mouse. + + - type: textarea + id: what + attributes: + label: What you want + description: The behaviour, and what you are trying to read or do with it. + validations: + required: true + + - type: textarea + id: why + attributes: + label: Why the current behaviour is not enough + description: What you do today instead, and where it falls short. + validations: + required: true diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..00307a6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,97 @@ +# Contributing to tread + +Thanks for looking. This document exists mostly to save you effort: `tread` has +a few constraints that are unusual enough that a well-written patch can still be +unmergeable, and it is fairer to say so before you write it than after. + +`SPEC.md` is the binding contract for behaviour, and `CLAUDE.md` describes the +module layout. Read whichever covers what you are touching. + +## What will be declined + +These are not preferences to be argued out of. They are the reason the project +exists in this shape. + +- **Adding a dependency.** `[dependencies]` and `[dev-dependencies]` are empty + and stay empty — no `libc`, no `crossterm`, no `windows-sys`, nothing for + tests. The markdown, CSV and JSON parsers, the Unicode width table, the ANSI + writer, the key decoder, base64 and every syscall are hand-written here on + purpose. A patch that adds a crate will be declined even if the crate is + better than what it replaces. +- **Capturing the mouse.** No `?1000h`, `?1002h`, `?1006h`; on Windows, never + setting `ENABLE_MOUSE_INPUT` and never clearing `ENABLE_QUICK_EDIT_MODE`. + Terminal-native drag-select must keep working, because being able to select + text with the mouse is a product requirement — not a missing feature. +- **`unsafe` outside the backends.** All of it lives in `src/sys/unix.rs` and + `src/sys/windows/ffi.rs`. Everything else carries `#![deny(unsafe_code)]` or + contains none, including the pure `abi.rs` / `layout.rs` files. +- **A platform `#[cfg]` above `src/sys/`.** Path syntax, cache locations and + similar *conventions* are pure functions of `plat::Platform`, so the other + OSes' rules are covered by `cargo test` on Linux. A new `cfg(target_os)` in + `render`, `pager` or `nav` is a design problem, not a fix. +- **`println!` / `eprintln!` for UI.** Frames go through `Term`. `eprintln!` is + only for fatal startup errors, as `tread: `. +- **Files over 500 lines or functions over 50.** Split the module instead. + +## What is welcome + +Bug reports with a file that reproduces them, especially from a terminal or OS +combination the project cannot test. New `--lens` dialects (see +`docs/lenses.md` — a module plus one line in `LENSES`). New formats behind the +`Source` seam. Rendering fixes for scripts and widths that are wrong today. +And anything on Windows: see below. + +## Before opening a pull request + +```sh +cargo test # must be green +cargo clippy --all-targets -- -D warnings # CI gates on this +cargo check --target x86_64-pc-windows-msvc # and aarch64-pc-windows-msvc, + # and x86_64-pc-windows-gnu +cargo check --target aarch64-apple-darwin # and x86_64-apple-darwin +``` + +CI runs the full suite natively on Linux, macOS and Windows for both +architectures, so you do not need those machines yourself — but a cross `check` +locally catches the common mistakes in seconds rather than minutes. + +`cargo fmt` is **not** run on this tree. It follows a hand style and rustfmt +would rewrite thousands of lines; please match the surrounding code instead of +reformatting it. + +Tests live beside the code in `#[cfg(test)]`; golden renders live in `tests/`. +Assert on ANSI-stripped text plus separate style spans, so a palette change does +not break every test. Regenerate goldens with +`UPDATE_GOLDEN=1 cargo test --test golden_files`. `CLAUDE.md` § *Build, run, +test* has the rest — the corpus checks and the soak harnesses — and is where a +change to any of this belongs. + +## Windows especially + +The console backend is hand-written against `kernel32` and is the least-proven +part of the project: the suite runs on real Windows runners in CI, but there is +no ConPTY soak harness, so the interactive pager on Windows has only been +exercised by hand. `docs/windows.md` is precise about what is and is not +verified. If you run `tread` on Windows and something is wrong — rendering, +resize, drag-select, exit behaviour — that report is more valuable than most +patches, and please say which terminal (Windows Terminal, conhost, VS Code) and +which PowerShell. + +Do not claim a Windows behaviour works unless a command printed it or you +watched a session do it, and keep that document's verified / not-verified lists +honest when you change the backend. + +## Commits + +`scope: imperative description`, lowercase — `code: read python and java`, not +`add DirSource`. The scope is *where* the change lives, not what kind of change +it is; there is no `feat:` / `fix:` vocabulary, because nothing is generated +from the log. Say what changed in behaviour and let the diff show the files. + +One logical change per commit, each building and passing on its own, and please +fold a fix-up into the commit it repairs before asking for a merge. A feature +branch is not squashed to a single commit — a large feature is exactly what +someone will `git bisect` through later. + +`CLAUDE.md` § *Commits and history* is the full version of this rule and the +one that wins if these two ever disagree. diff --git a/README.md b/README.md index 8007685..fd57d98 100644 --- a/README.md +++ b/README.md @@ -574,8 +574,10 @@ any UI path. ## Docs How it is built and how it is proven lives in [`docs/`](docs/) — the module -map, the test layers, and what is and is not verified about the Windows -console backend. [`SPEC.md`](SPEC.md) is the binding contract for behaviour. +map, the test layers, how to cut a release, and what is and is not verified about +the Windows console backend. [`SPEC.md`](SPEC.md) is the binding contract for +behaviour, and [`CONTRIBUTING.md`](CONTRIBUTING.md) says what a patch must not +do — chiefly add a dependency or capture the mouse. ## License diff --git a/docs/releasing.md b/docs/releasing.md new file mode 100644 index 0000000..b8c8a13 --- /dev/null +++ b/docs/releasing.md @@ -0,0 +1,90 @@ +# Cutting a release + +The whole process is a signed tag; `release.yml` does the rest. What follows is +mostly the order that avoids re-doing it. + +## 1. The version lives in three places + +```sh +$EDITOR Cargo.toml # version = "X.Y.Z" +cargo build # updates Cargo.lock's own entry — commit it +$EDITOR README.md # the `cargo tree` sample: `tread vX.Y.Z` +grep -rn 'tread v0\.' README.md # nothing may still name the old version +``` + +`tread --version` prints what `Cargo.toml` says. A tag that disagrees with it +ships a binary that lies about itself, and nothing catches that automatically — +the README sample in particular is a copy no build touches, so it is the one +that gets forgotten. `v0.2.0` mentions in `CLAUDE.md` and `docs/windows.md` are +different: they record *when* something was verified by hand, and must not be +bumped just because a new version shipped. + +## 2. Land it on master and wait for green + +The bump goes through a pull request like anything else — the branch is named +`release/vX.Y.Z` by convention: + +```sh +git commit -am "release: bump to X.Y.Z" +git push -u origin release/vX.Y.Z +gh pr create --base master --title "release: bump to X.Y.Z" +gh pr checks --watch # ci.yml: six native targets, must be success +gh pr merge --merge +gh run list --branch master --limit 1 # ci.yml again, on the merge commit +``` + +The run on the PR proves the branch; the run on master proves the commit you +are about to tag, which is a different commit once it is merged. Wait for that +second one. + +**Do not tag before CI is green on the commit you intend to tag.** Before +`ci.yml` existed, the Windows suite first ran at publish time — a test that +passed on Linux and failed on Windows reached a tag, and the tag had to be +deleted and re-pushed. That is the failure this step exists to prevent. + +## 3. Tag, signed, with a message + +```sh +git checkout master && git pull # tag the merge commit, not the branch head +git tag -m "tread vX.Y.Z" vX.Y.Z +git push origin vX.Y.Z +``` + +`tag.gpgsign` is on, so a tag is an annotated object and **`-m` is mandatory** — +a bare `git tag vX.Y.Z` fails with `fatal: no tag message?`. Verify before +pushing if you like: `git tag -v vX.Y.Z` should report a good signature. + +## 4. Watch it publish + +```sh +gh run list --limit 1 +gh release view vX.Y.Z --json assets --jq '.assets[].name' +``` + +Six archives plus `SHA256SUMS`. The workflow builds and tests each target on its +own native runner, so a green run means every artifact was tested on the +architecture it ships for. + +## If the release run fails + +Land the fix on master the same way — a branch and a PR — then move the tag: + +```sh +git tag -d vX.Y.Z && git push origin :refs/tags/vX.Y.Z +git tag -m "tread vX.Y.Z" vX.Y.Z && git push origin vX.Y.Z +``` + +The publish step replaces assets rather than colliding with existing ones, so a +re-tag is safe and needs no cleanup on the release itself. Moving a tag is not +the rewriting of published history that `CLAUDE.md` forbids: the commits on +master are untouched, and the tag is only a label being corrected. Once a +release is announced, though, the label has been read by other people — from +that point a mistake gets a new version, not a moved tag. + +## Afterwards + +- `install.sh` and `install.ps1` resolve the newest release, so nothing needs + updating for the new version to be installable. +- If the release is the first to exercise something on real hardware — a new + platform, a new installer path — update `docs/windows.md`'s verified / + not-verified lists. That document is only worth having while it is honest.