Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 62 additions & 0 deletions .github/ISSUE_TEMPLATE/bug.yml
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
blank_issues_enabled: true
26 changes: 26 additions & 0 deletions .github/ISSUE_TEMPLATE/feature.yml
Original file line number Diff line number Diff line change
@@ -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
97 changes: 97 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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: <message>`.
- **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.
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
90 changes: 90 additions & 0 deletions docs/releasing.md
Original file line number Diff line number Diff line change
@@ -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.
Loading