Skip to content

Example style guide, syntax_tree formatter, 80-column examples - #19

Draft
tony wants to merge 10 commits into
masterfrom
example-style
Draft

tony wants to merge 10 commits into
masterfrom
example-style

Conversation

@tony

@tony tony commented Oct 4, 2026 •

Copy link
Copy Markdown
Contributor
  • syntax_tree formats Ruby at 100 columns for source and 80 under examples/ (no formatter ran, so line width was unenforced).
  • CI gates the format with scripts/format --check.
  • The shared libtmux example rules arrive with a stdlib Python check that holds every Markdown page to 80.

Merge after libtmux/docs#101 deploys: it makes 80 columns fit a libtmux.org code block from 1024 px up. Run against origin/master, the checker reports 170 lines over 80 in 19 files.

What changed

Policy

  • .github/WRITING.md gains an ## Examples section after ## Markdown and examples (plus a ### Code blocks heading the shared text links to). ## Markdown and examples keeps its existing example rules. The "In this repository" block names the 80-column limit and its config, says syntax_tree skips Markdown fences and does not wrap comments, and lists the <!-- example: ID --> markers over # docs:begin NAME and bundle exec scripts/format, which re-syncs excerpts through scripts/examples --write, as the sync command.
  • AGENTS.md routes code examples to it.

Tooling

  1. scripts/format and syntax_tree ~> 6.3 in a development group. It writes until the output is stable, then runs scripts/examples --write and scripts/types --write to re-sync quoted excerpts. --check is read-only.
  2. Ruby(style): one mechanical reformat, 141 files (+15539/-6114): 136 Ruby files and 5 re-synced Markdown copies, no hand edits.
  3. CI runs scripts/format --check in the compatibility workflow.
  4. .git-blame-ignore-revs lists that reformat commit; run git config blame.ignoreRevsFile .git-blame-ignore-revs to skip it locally.
  5. scripts/check_example_width.py and .github/example-width.toml run in the style job. The config reads every **/*.md page, examples/**/*.rb and examples/**/*.yaml, and excludes examples/manifest.json with a reason (a machine-read index whose strings the example tests compare byte for byte). One [[allow]] entry: the deliberately wide Bad line in WRITING.md's port block.
  6. .github/CONTRIBUTING.md documents the check.

Examples

  • One commit per example: Name the shell setup, Name request parts, Wrap the dry-run command.

Evidence

  • Four formatters compared on Ruby 4.0.7 over the same 146 files (the count the syntax check and rubocop report). syntax_tree 6.3.0 is the only one that wraps to a hard width and takes the width per invocation (--print-width), so source stays at 100 and examples/ goes to 80. Its first write is not idempotent on this tree, hence the repeat loop. The check took 10.3 s in CI. Sources: usage, gem, cli.rb.
  • Rejected RuboCop Layout/LineLength with -A (split a heredoc call in test/unit/process_test.rb and broke parsing), Standard and rufo (no width option, so they cannot enforce 80 or 100).
  • An unformatted line appended to a tracked file failed scripts/format --check and passed once restored (scripts/format reads git ls-files, so an untracked file would not fail it).
  • Rejected Ruby-only RuboCop for the width check: it splits heredocs and cannot read Markdown fences.
  • The Python width check reads its settings with tomllib, which needs Python 3.11 (docs); ubuntu-24.04 runners ship 3.12.3 (runner-images ubuntu24/20261004.327).
  • Maintenance risk: syntax_tree 6.3.0 parses with Ripper (class Parser < Ripper), while Ruby 3.4 made Prism its default parser (NEWS).

How to verify

$ mise exec -- bundle exec scripts/format --check
$ python3 scripts/check_example_width.py --self-test
$ python3 scripts/check_example_width.py
$ mise exec -- bundle exec scripts/examples

@tony
tony force-pushed the example-style branch 4 times, most recently from f4b87f5 to 7e5382c Compare October 4, 2026 16:54
@tony
tony force-pushed the example-style branch 5 times, most recently from 7d63629 to 412e01d Compare October 4, 2026 23:18
@tony
tony force-pushed the example-style branch 3 times, most recently from 8fe9a89 to 53893ed Compare October 5, 2026 05:56
@tony
tony force-pushed the example-style branch 5 times, most recently from da1eed4 to 1cee3c5 Compare October 5, 2026 23:20
@tony
tony force-pushed the example-style branch 4 times, most recently from a462f2f to c6391cc Compare October 11, 2026 06:22
@tony
tony force-pushed the example-style branch 2 times, most recently from 93e1747 to 9c0ef68 Compare October 11, 2026 10:45
@tony
tony force-pushed the example-style branch 2 times, most recently from f950125 to ba04a4e Compare October 11, 2026 12:53
tony added 10 commits October 12, 2026 04:15
why: Ruby has no formatter here, so line width is unenforced and
examples cannot be held to 80 columns, the width the shared libtmux
example rules set (libtmux-powershell#1). A bakeoff ran four formatters
on Ruby 4.0.7 over the same tree (the 146 files the syntax check reads):

- syntax_tree 6.3.0 wraps to a hard width and takes the width per
  invocation (`--print-width`), so source can stay at 100 while
  examples/ goes to 80. Its first write is not idempotent on this tree,
  so scripts/format repeats until `stree check` passes. The reformat
  changes 136 Ruby files and moves lines that the generated API
  reference and example excerpts quote, so scripts/format re-syncs those
  5 Markdown files. The check took 10.3 s in CI:
  https://github.com/libtmux/libtmux-ruby/actions/runs/38133086130/job/114451763543

Rejected:
- RuboCop Layout/LineLength with -A: split a heredoc call in
  test/unit/process_test.rb and broke parsing.
- Standard: no width option, cannot enforce 80 or 100.
- rufo: no width option, cannot enforce 80 or 100.

Sources, pinned:
- https://github.com/ruby-syntax-tree/syntax_tree/tree/v6.3.0#usage
  (`--print-width`, `stree check`, `stree write`)
- https://rubygems.org/gems/syntax_tree/versions/6.3.0
- https://github.com/ruby-syntax-tree/syntax_tree/blob/v6.3.0/lib/syntax_tree/cli.rb

what:
- Add syntax_tree ~> 6.3 in a development group; update Gemfile.lock
- Add scripts/format: 100 columns for source, 80 under examples/,
  write until stable, then run scripts/examples --write and
  scripts/types --write; `--check` is read-only
why: Adopt the formatter in one mechanical change so blame can skip it.
The change is the formatter's output and the copies it moves; no line
was edited by hand.

what:
- Run `bundle exec scripts/format`: source at 100 columns, examples
  at 80 columns
- Re-sync the example excerpts in docs and the public API reference
  that quote moved lines
why: Every Ruby file now follows syntax_tree's layout; without a gate
the next change drifts again. `scripts/format --check` is read-only and
exits non-zero on any file the formatter would change; an
unformatted line appended to a tracked file failed it and passed once
restored.

what:
- Run `scripts/format --check` in the compatibility workflow
- CONTRIBUTING: the write and check commands beside the other gates
why: The reformat touched nearly every Ruby file; without this, git
blame attributes those lines to a commit that changed only layout.

what:
- Add .git-blame-ignore-revs listing the reformat commit:
  e6a3872
- Enable locally with `git config blame.ignoreRevsFile
  .git-blame-ignore-revs`; GitHub's blame view reads it on its own
why: The formatter broke the one-entry environment hash across three
lines inside the new_session call, which buried the point of the
argument: the shell skips its startup file so the pane prompt is
predictable.

what:
- Bind `{ "ENV" => "/dev/null" }` to `quiet_shell` above the call
- Pass `environment: quiet_shell`, leaving one argument per line
why: The formatter split the empty capabilities hash into `{` and `}`
on separate lines and spread the two-field client info over four, and
the shell script literal ran past 80 columns. None of those breaks helps
a reader following the protocol exchange.

what:
- Bind `client_capabilities` and `client_info` before the initialize
  request
- Build the shell script from three commands joined with "; ", one per
  array element, which yields the identical string
- Re-sync the docs/recipes.md excerpts of this program
why: The console command in the release guide was wider than 80 columns.

what:
- Continue the command after `/usr/bin/time -p` with a backslash
why: Example width, markers, and sync rules were unwritten, so authors
could not tell which lines a formatter owns and which a width check
would own.

what:
- Add the shared Examples section after Markdown and examples
- Add the repository's limit, formatter scope, example markers and sync
  commands, with a real before and after
- Anchor the Code blocks rules the shared section links to
why: Agents editing an example program or code block need to find the
Examples rules.

what:
- Add code examples to the WRITING.md routing line and link the section
why: Examples render in fixed-width boxes that scroll sideways, and 80
columns fits a libtmux.org code block in a laptop-width window once
libtmux/docs#101 sizes the code font to fit (78 columns at 1024 px in
Firefox, WebKit and CI's Chrome without it). syntax_tree holds program
source under examples/ to 80, but README and docs code blocks, and
comments that no formatter wraps, were unchecked. Run against trunk
8640cf1, this checker and config report 170 lines over 80 in 19 files.

One shared checker serves each port that adopts it, so the rule behaves
the same in each, and its --self-test plants a failure for each rule.

Rejected:
- A checker per port: thirteen implementations with mismatched
  coverage.
- An advisory report: no enforcement, and the backlog regrows.
- Ruby-only RuboCop Layout/LineLength: splits heredoc calls and cannot
  read Markdown fences.

Source, pinned: tomllib is in the standard library from Python 3.11
(https://docs.python.org/3.11/library/tomllib.html); ubuntu-24.04
runners ship Python 3.12.3:
https://github.com/actions/runner-images/blob/ubuntu24/20261004.327/images/ubuntu/Ubuntu2404-Readme.md#L28

what:
- Add scripts/check_example_width.py
- Add .github/example-width.toml: every Markdown file (`**/*.md`), the
  example programs and the workspace file under examples/ (`*.rb`,
  `*.yaml`), one allow entry for the Bad example in WRITING.md, and
  the checker and shared-text digests from --digest
- Exclude examples/manifest.json: its output strings are compared byte
  for byte by the example tests, so its lines cannot be rewrapped
- Run the self-test and the check in the style CI job
- Document both commands in CONTRIBUTING

This branch was previously deployed

1 inactive deployment
docs-preview — cca64163 Deployed Oct 12, 2026 by tony via publish (pr-19, pr, false, docs-preview, true) / publish #159
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant