v0.10.0 d5d679d

AGENTS.md RawHistoryFolder

Repository rules

  • Use Go 1.27 only; normal builds and tests use CGO_ENABLED=0.
  • Keep a lightweight hexagonal architecture: core imports only stdlib and ports.
  • Owner goroutines own window state; no mutex on window state.
  • Use zerowrap logging with a component field on every entry.
  • Run tests with -race.
  • Use signed conventional commits: type(scope): description.

Mocks (hard rule)

Test doubles are always generated by Mockery v3 (testify template). Never handwrite them.

  • No handwritten fakes, stubs or spies. This covers any test type standing in for a project interface, and function fields swapped by tests (x.ioctl = func...). make check runs fakes-check, which rejects fake/stub/spy/dummy/mock type names in tests.
  • Every seam is an interface. When a test needs to replace a dependency, add an interface and generate its mock:
    • Cross-layer dependencies go in internal/ports. Mocks: internal/mocks/ports, package portsmocks, type MockX.
    • Adapter-internal seams (e.g. a kernel ioctl) stay unexported in the adapter. Mocks: <name>_mock_test.go in the same package.
  • Add a .mockery.yml entry for each new interface, run make mocks and commit the generated files. make mocks-check (CI) fails if they are stale or missing.
  • Use mocks through .EXPECT(). Record calls with RunAndReturn when a test inspects arguments.
  • Channel ports (sealed message interfaces such as ports.ClientEvent or ports.OutputEvent) are tested by sending messages, not with mocks.
  • Not doubles, so allowed:
    • real protocol clients in wayland tests (wlturbo proxies);
    • real in-memory implementations of std interfaces (e.g. a locked bytes.Buffer as io.Writer);
    • production constructor parameters such as NewRenderer func(w, h) (ports.Renderer, error), where tests return a generated mock;
    • channels passed to app.run to inject input or observe scenes (channel ports).

End-to-end tests (headless backend)

Unit tests are not enough for user-facing behavior (binds, gestures, window placement, config keys). Test it end to end on the headless backend before declaring it done; see docs/headless.md.

  • Build the branch binary (CGO_ENABLED=0 go build -o <tmp>/neferwl ./cmd/neferwl) and run it with a throwaway config: <tmp>/neferwl --backend=headless --config <tmp>/config --no-xwayland --screenshot <tmp>/shots --input <script> --timeout 10s.
  • Input scripts drive keys and gestures (key Super+s, swipe4 down, sleep 1s); see the table in docs/headless.md.
  • Logs go to $XDG_STATE_HOME/neferwl/runs/headless/latest.log, not stderr. Read the headless WAYLAND_DISPLAY from its listening entry.
  • Isolate from the user's live session: run the headless compositor, its clients and neferwl state with env -u NEFERWL_STATE -u NEFERWL_SLOT WAYLAND_DISPLAY=<headless>. NEFERWL_STATE wins over WAYLAND_DISPLAY and would read the live session's state.
  • Check results with WAYLAND_DISPLAY=<headless> neferwl state (windows, stash index/count, visibility) and the latest.png screenshot.

Checks before merge

make check, make race, make mocks-check and staticcheck ./... must pass. User-facing changes are also tested end to end on the headless backend.

source
1# Repository rules
2
3- Use Go 1.27 only; normal builds and tests use CGO_ENABLED=0.
4- Keep a lightweight hexagonal architecture: core imports only stdlib and ports.
5- Owner goroutines own window state; no mutex on window state.
6- Use zerowrap logging with a `component` field on every entry.
7- Run tests with `-race`.
8- Use signed conventional commits: `type(scope): description`.
9
10## Mocks (hard rule)
11
12Test doubles are always generated by Mockery v3 (`testify` template). Never handwrite them.
13
14- **No handwritten fakes, stubs or spies.** This covers any test type standing in for a project interface, and function fields swapped by tests (`x.ioctl = func...`). `make check` runs `fakes-check`, which rejects `fake`/`stub`/`spy`/`dummy`/`mock` type names in tests.
15- **Every seam is an interface.** When a test needs to replace a dependency, add an interface and generate its mock:
16  - Cross-layer dependencies go in `internal/ports`. Mocks: `internal/mocks/ports`, package `portsmocks`, type `MockX`.
17  - Adapter-internal seams (e.g. a kernel ioctl) stay unexported in the adapter. Mocks: `<name>_mock_test.go` in the same package.
18- **Add a `.mockery.yml` entry** for each new interface, run `make mocks` and commit the generated files. `make mocks-check` (CI) fails if they are stale or missing.
19- Use mocks through `.EXPECT()`. Record calls with `RunAndReturn` when a test inspects arguments.
20- Channel ports (sealed message interfaces such as `ports.ClientEvent` or `ports.OutputEvent`) are tested by sending messages, not with mocks.
21- Not doubles, so allowed:
22  - real protocol clients in wayland tests (`wlturbo` proxies);
23  - real in-memory implementations of std interfaces (e.g. a locked `bytes.Buffer` as `io.Writer`);
24  - production constructor parameters such as `NewRenderer func(w, h) (ports.Renderer, error)`, where tests return a generated mock;
25  - channels passed to `app.run` to inject input or observe scenes (channel ports).
26
27## End-to-end tests (headless backend)
28
29Unit tests are not enough for user-facing behavior (binds, gestures, window placement, config keys). Test it end to end on the headless backend before declaring it done; see [docs/headless.md](docs/headless.md).
30
31- Build the branch binary (`CGO_ENABLED=0 go build -o <tmp>/neferwl ./cmd/neferwl`) and run it with a throwaway config: `<tmp>/neferwl --backend=headless --config <tmp>/config --no-xwayland --screenshot <tmp>/shots --input <script> --timeout 10s`.
32- Input scripts drive keys and gestures (`key Super+s`, `swipe4 down`, `sleep 1s`); see the table in docs/headless.md.
33- Logs go to `$XDG_STATE_HOME/neferwl/runs/headless/latest.log`, not stderr. Read the headless `WAYLAND_DISPLAY` from its `listening` entry.
34- Isolate from the user's live session: run the headless compositor, its clients and `neferwl state` with `env -u NEFERWL_STATE -u NEFERWL_SLOT WAYLAND_DISPLAY=<headless>`. `NEFERWL_STATE` wins over `WAYLAND_DISPLAY` and would read the live session's state.
35- Check results with `WAYLAND_DISPLAY=<headless> neferwl state` (windows, stash index/count, visibility) and the `latest.png` screenshot.
36
37## Checks before merge
38
39`make check`, `make race`, `make mocks-check` and `staticcheck ./...` must pass.
40User-facing changes are also tested end to end on the headless backend.

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 25

Tags 10

↑↓ moveenter openesc close