.github/CONTRIBUTING.md

Source at 4d73c9795adca3e49eea74d1d2cbbbbdcbea0b6c

SHA-256: 201eb88bc51943b5a3e01740b80b0392e55f444f31dfee699050bb59e32644e5

# Contributing

This repository uses a Rebar umbrella with the core OTP application under
apps/. The [project policy](../docs/project-policy.md) defines the package
boundary and OTP runtime dependencies.
Current checks cover models, the helper adapter, owned fixtures, borrowed
endpoints, operation ownership, initial domain commands, captured graphs,
local filtering, bounded JSON, source-query planning and package structure.
Full command, consumer and CI qualification remains in the epic.

[AGENTS.md](../AGENTS.md) governs scope and change discipline.
[WRITING.md](WRITING.md) governs prose and commit messages.

## Setup

Use mise to install the exact development versions in
[.tool-versions](../.tool-versions). Initial development targets only the
latest stable Erlang/OTP release. Check the
[official downloads](https://www.erlang.org/downloads) when updating OTP,
then update the exact pin. Older OTP compatibility is outside the current
scope. Install tools before timing checks:

```console
$ mise install
```

Check the selected versions:

```console
$ mise current
```

Verify that the pinned build tool runs on the selected Erlang runtime:

```console
$ mise exec -- rebar3 version
```

The pure model checks do not start tmux. Live integration checks must use
owned sockets and prove cleanup. Selecting a toolchain does not establish
runtime compatibility.

## Current checks

Run a focused EUnit module after changing its critical behavior:

```console
$ time python3 tools/check.py inner \
    --module tmux_model_tests
```

Run the unit, generated-source and tracked whitespace checks:

```console
$ time python3 tools/check.py mid
```

The mid loop also checks public EEP-48 documentation/spec coverage, generated
field references, guide links and exact example excerpts. Write contracts in
`-moduledoc` and `-doc`; follow the native
[interlinking rules](WRITING.md#interlinking) for modules, functions, types and
callbacks. Use `ct_doctest` shell transcripts for
native code blocks. Prose-only contracts need no artificial example; every
advertised Erlang block must execute without skips.

[Building the API browser](../docs/api.md) explains the pinned ExDoc tool,
captured source links and working-tree provenance. The HTML build treats
warnings and broken local links/anchors as failures. Add complete runnable
programs under examples/ and drift-checked excerpts to their reader guides.

The example runner marks `_build/checks/examples.json` as `RUNNING` before
starting work. Success replaces it with `PASS`; a caught failure records
`FAIL`. After initialization, an interrupted run leaves `RUNNING` rather than
an earlier success. Failed initialization prevents examples from starting.
Only a completed `PASS` receipt supplies runtime example evidence. Scratch
directories use `TMPDIR` when set, otherwise `/tmp`.

Run compilation, native helper qualification, Dialyzer, real subprocess/tmux
integration, executable docs and the external OTP archive consumer:

```console
$ time python3 tools/check.py outer
```

These commands retain command output and timing under _build/checks/.
The Python runner needs Python 3.12 or newer from the development host.
It times each complete child command, including mise and VM startup; the
shell time command measures the complete loop invocation.
The runner defaults to four Erlang schedulers to bound its share of a busy
development host. An explicit ERL_FLAGS overrides that test profile; receipts
record the selected flags. This does not configure the installed application.

[Portable filter fixtures](../test/fixtures/README.md) define shared graph,
result and validation cases. EUnit consumes them and checks composed wire
round trips. Other-port conformance remains a separate qualification gate.

The restricted ASCII regex dialect has a separate
[reference-engine check](../tools/regex-conformance/README.md). Node and Rust
are test-only tools; the core remains OTP-only. The mid loop checks fixture
drift, while CI runs matching against PCRE2, JavaScript and Rust regex.

[CI source builds](../tools/ci/README.md) explains the pinned tmux matrix,
cache validation and separate PropEr profile. CI uses setup-beam's installed
tools directly; the local runner uses mise.

Edit schema/entities.json, then regenerate the native records and registry:

```console
$ mise exec -- escript tools/generate_schema.escript
```

The generator uses OTP JSON. Generated files are checked in so package
consumers do not need the generator. Do not hand-edit generated Erlang.

The option catalogue uses the same pinned tmux source commits as CI. After
changing those pins, refresh it from a local tmux Git clone:

```console
$ python3 tools/generate_options.py \
    --refresh-from /path/to/tmux
```

This maintainer operation needs a C preprocessor to expand hook macros. The
mid loop only checks the committed JSON against generated Erlang/reference
files; consumers need neither the tmux checkout nor this generator.

The native command catalogue records parser declarations and selected feature
minimums from those same pins. Refresh its data and reference together:

```console
$ python3 tools/generate_commands.py \
    --refresh-from /path/to/tmux
```

The mid loop checks source-pin identity and generated drift without reading a
tmux checkout. Native command discovery does not establish facade coverage,
complete argument validation or runtime qualification.

The core application builds its Linux helper with make and a C11 compiler.
The pinned source and its license live under apps/libtmux_erlang/c_src/.
The helper checks use events and PID descriptors to verify owned retirement;
the Erlang adapter checks require retirement proof and actual helper exit.
Output limits reserve one additional byte per stream to distinguish EOF from
overflow. Completed results release the accumulator's chunk references.

With Clang 18 and its sanitizer runtime installed, run the additional native
outer check:

```console
$ time python3 tools/check_helper_native.py
```

This compiles the helper with AddressSanitizer and UndefinedBehaviorSanitizer
and runs its existing lifecycle/protocol suite. A separate libFuzzer harness
executes 10,000 parser inputs with fragmented reads, partial frames and EOF.
Its fork stub prevents fuzz bytes from executing a child; the protocol suite
exercises real owned children. The check records compiler/source identities,
seed, whole-command times and logs under _build/checks/helper-native/. A crash
input is retained there. CI runs this check on Linux x86_64 and arm64.
This bounded corpus is regression evidence, not exhaustive protocol proof.

Prepare the pinned, test-only Hex package tools before timing installation
checks. This downloads verified tool archives and compiles the registry helper;
it does not publish packages or change the user's Rebar3 configuration:

```console
$ mise exec -- python3 tools/check_source_package.py --prepare
```

Run the source-installation outer check with the selected supported tmux:

```console
$ time mise exec -- python3 tools/check_source_package.py
```

It builds the core with `rebar3 hex build package`, then serves that exact
tarball through a signed local registry. A fresh consumer declares only the
core and builds the C helper.
A missing compiler must fail installation before the successful build. The
same installed examples and native-record checks used by the compiled archive
run against this installation. Tarballs, source/tool hashes, logs and timings
remain under _build/source-package-check/. CI runs this on both architectures
with tmux 3.3a and 3.8. Registry publication remains a separate gate.

Common Test selects tmux from LIBTMUX_TEST_TMUX, or PATH when unset. Set that
variable to an absolute executable path to qualify a particular release.
The fixture owns a foreground server on a private socket. A test-only Linux
inotify watcher waits for its post-listen permission event; startup never
polls a borrowed server. The watcher uses the host's /usr/bin/python3.
Passing this local suite does not establish the complete CI version matrix.

Dialyzer includes Common Test in its analysis table because the external
consumer executes ct_doctest. Its first run builds the table; retain that
setup time when reporting the outer check.

The installed archive check also runs a separate constructor-type consumer.
It executes valid maps, imports the generated public input types, and requires
four deliberate invalid calls to produce Dialyzer diagnostics. Expected
negative diagnostics remain in the package receipt. See
[type boundaries](../docs/api.md#types-at-application-boundaries) for the
current generic-return limitation.

Validate the repository settings after editing them:

```console
$ time jq empty .github/repository.json
```

Before handoff, check changed files for whitespace errors:

```console
$ time git diff --check
```

Check staged files before committing:

```console
$ time git diff --cached --check
```

Git does not include untracked files in those checks; inspect newly created
files before staging them. Verify relative Markdown links, the
`CLAUDE.md -> AGENTS.md` symlink, and the settings on both GitHub repositories.
Compiler warnings are errors. The formatting policy below records the
qualified tool limitation. Package publication and the complete feature matrix
remain separate implementation gates.

## Formatting

Maintain Erlang layout manually and keep reader examples within 80 columns.
Generated files remain owned by their generators.

The released [erlfmt 1.8.0](https://github.com/WhatsApp/erlfmt/releases/tag/v1.8.0)
does not parse OTP 29 native-record declarations. Qualification covered a
minimal native record and this project's generated model, both accepted by
the OTP 29.1.2 compiler. erlfmt reported syntax errors for those declarations.
Its [parser fallback](https://github.com/WhatsApp/erlfmt/blob/v1.8.0/src/erlfmt.erl#L530-L534)
preserves unparsed forms, and `--check` can still return zero. Exit status
alone therefore does not qualify whole-file formatting.

Formatter enforcement is deferred. Recheck released candidates against all
syntax used here before enabling one; require no parser diagnostics,
preserved semantics, stable generated output and the example width limit.
Upstream tracks native-record support in
[issue 377](https://github.com/WhatsApp/erlfmt/issues/377).

## Check budgets

Time the entire command, including startup and setup. Add tests only for
critical behavior once implementation begins.

| Loop | Budget | Library target | Scope |
| --- | --- | --- | --- |
| Inner | Under 5s | Under 2s | Changed critical behavior or metadata |
| Mid | Under 30s | Under 10s | Unit, lint, and generated-file checks |
| Outer | Under 5 min | Under 60s | Builds, types, integration, and matrices |

The inner and mid loops must not install tools, use the network, build for
production, launch browsers, sleep, or scan broad corpora. Use events or
subscriptions instead of arbitrary waits. Investigate timeouts and waits
over one second as structural defects. Tag slow tests with a one-line reason
and run them in the outer loop. Fix a loop that exceeds its budget before
adding tests; do not raise the budget. Benchmarks are separate: each run
stays under 10 minutes and the full sweep under one hour.

## Review

Keep changes focused. Follow native Erlang conventions and preserve existing
work. A review description explains the resulting behavior and reports
relevant checks, whole-command durations, failures, and skipped checks.
Implementation, release, and compatibility claims need their own evidence.

Real-tmux checks follow the ownership rules in [AGENTS.md](../AGENTS.md).
Package, CI, documentation export and release claims require their respective
epic gates; current local checks do not pass unimplemented surfaces.