Repository navigation
Conversation
tony
force-pushed
the
example-style
branch
4 times, most recently
from
October 4, 2026 16:54
f4b87f5 to
7e5382c
Compare
tony
force-pushed
the
example-style
branch
5 times, most recently
from
October 4, 2026 23:18
7d63629 to
412e01d
Compare
tony
force-pushed
the
example-style
branch
3 times, most recently
from
October 5, 2026 05:56
8fe9a89 to
53893ed
Compare
tony
force-pushed
the
example-style
branch
5 times, most recently
from
October 5, 2026 23:20
da1eed4 to
1cee3c5
Compare
tony
force-pushed
the
example-style
branch
4 times, most recently
from
October 11, 2026 06:22
a462f2f to
c6391cc
Compare
tony
force-pushed
the
example-style
branch
2 times, most recently
from
October 11, 2026 10:45
93e1747 to
9c0ef68
Compare
tony
force-pushed
the
example-style
branch
2 times, most recently
from
October 11, 2026 12:53
f950125 to
ba04a4e
Compare
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
examples/(no formatter ran, so line width was unenforced).scripts/format --check.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.mdgains an## Examplessection after## Markdown and examples(plus a### Code blocksheading the shared text links to).## Markdown and exampleskeeps 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 NAMEandbundle exec scripts/format, which re-syncs excerpts throughscripts/examples --write, as the sync command.AGENTS.mdroutes code examples to it.Tooling
scripts/formatandsyntax_tree ~> 6.3in a development group. It writes until the output is stable, then runsscripts/examples --writeandscripts/types --writeto re-sync quoted excerpts.--checkis read-only.Ruby(style): one mechanical reformat, 141 files (+15539/-6114): 136 Ruby files and 5 re-synced Markdown copies, no hand edits.scripts/format --checkin the compatibility workflow..git-blame-ignore-revslists that reformat commit; rungit config blame.ignoreRevsFile .git-blame-ignore-revsto skip it locally.scripts/check_example_width.pyand.github/example-width.tomlrun in the style job. The config reads every**/*.mdpage,examples/**/*.rbandexamples/**/*.yaml, and excludesexamples/manifest.jsonwith 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..github/CONTRIBUTING.mddocuments the check.Examples
Name the shell setup,Name request parts,Wrap the dry-run command.Evidence
--print-width), so source stays at 100 andexamples/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.Layout/LineLengthwith-A(split a heredoc call intest/unit/process_test.rband broke parsing), Standard and rufo (no width option, so they cannot enforce 80 or 100).scripts/format --checkand passed once restored (scripts/formatreadsgit ls-files, so an untracked file would not fail it).tomllib, which needs Python 3.11 (docs); ubuntu-24.04 runners ship 3.12.3 (runner-images ubuntu24/20261004.327).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