Project
Contributing
How to build tui4s, the checks that a change must pass, and where the rules are.
git clone --recurse-submodules https://github.com/yuri4n/tui4s
cd tui4s
nix develop # JDK 25, sbt, Node.js and the terminal test tools
sbt fmt # format the Scala and sbt files
sbt check # format, compile, lint, test, compatibility
examples/ptycheck/run.sh # the real-terminal checklist in a pseudo-terminal
The rules
- CONTRIBUTING.md is the rulebook, for humans and for agents. It starts with a quick path. Then it gives the toolchain, the commands, the rules for code, the purity rules, the versions and the release process.
- ARCHITECTURE.md tells how the runner works: the modules, the keys, the components, the layout and the scroll.
- AGENTS.md holds the rules for AI agents only. It imports the two other files.
- The decision records give the reason for each rule. ADR 0021 gives the reason for the three files.
The checks
| Check | Command | What it checks |
|---|---|---|
| The sbt checks | sbt check | The format, the compile with no warning in CI, the scalafix lint, all the tests, the binary compatibility. |
| The edge files | bash scripts/edge-check.sh | The headers of the edge files and the scalafix:ok comments. |
| The release rules | bash scripts/version-order-test.sh | The version form and order, the modules and the last tag of a module (scripts/release-lib.sh). |
| The release notes | bash scripts/changelog-section-test.sh | The extraction of the notes of a module from CHANGELOG.md (scripts/changelog-section.sh), and that each subsection ### tui4s-<module> under the first heading of CHANGELOG.md has text. |
| The PTY kit | examples/ptycheck/run.sh | Each example in a real pseudo-terminal: the keys, the signals and the restore of the terminal. Run it after a change to the terminal code. |
| The Markdown regions | MarkdownRegionsSuite (in sbt check) | Each Scala block of README.md and of these pages is the text of a region of a source file. |
| The docs build | pnpm install --frozen-lockfile && pnpm run build in docs | The site builds with no network access. Set NUXT_TELEMETRY_DISABLED=1. |
Use JDK 25, and run one sbt process at a time in one checkout. Never start a terminal UI with sbt run: use the start scripts (sbt examples/launchers, then examples/target/bin/<app>).
Write docs
- Write the docs, the comments and the Scaladoc in ASD-STE100 (Simplified Technical English): short sentences, one instruction in each.
- A Scala block of a docs page is the text of a region of a compiled source. Add the region to the source first, then copy its text.
MarkdownRegionsSuitechecks it.
Releases
The maintainer starts a release from the Actions form on main (ADR 0020). The workflow checks everything before it creates a tag, waits for one approval, and then publishes each module to Maven Central in the order of the dependencies. A pull request that changes a published module adds a line under ## [Unreleased] of CHANGELOG.md, in the subsection ### tui4s-<module>: that text becomes the release notes.
Report a problem
Use the issue forms. A security problem goes to the security policy. The planned features are issues: https://github.com/yuri4n/tui4s/issues.