VCS.md hardcodes someones.computer's scripts — soften the references, keep the rules #10

New issue

Open

opened 2026-08-07 10:31:56 +00:00 by geusebio · 0 comments

geusebio commented

2026-08-07 10:31:56 +00:00

Owner

VCS.md names concrete scripts, Make targets and console commands that only exist in
someones.computer. A project that consumes this submodule and doesn't happen to ship them
gets a rule pointing at a path that isn't there — so the rule reads as broken and gets
ignored, rather than applied in whatever form that project has.

The convention to follow already exists in this repo. README.md, Requirements on the
consuming project:

vcs-check and ci-local don't hardcode tool invocations — projects differ (host
composer vs. docker compose exec <service> ...; PHPUnit-only vs.
PHPUnit+PHPStan+php-cs-fixer). Instead they read the consuming project's own root
CLAUDE.md for a "Quality gate" table.

commands/vcs-check.md and commands/ci-local.md were written to that rule and are
described in README.md as "generic by design". VCS.md was not, and is now the odd one
out.

What is established

Surveyed against a90d415, every *.md in this repo:

Reference in `VCS.md`	Line(s)	Exists everywhere?
`composer test:coverage`	32, 39, 65, 209, 233	No — assumes ParaTest and a 100% gate
`bin/coverage-gate.php`	40	No — someones.computer's own script
`php bin/console lint:yaml config --parse-tags`	34, 209	Symfony-only, and assumes `config/`
`php bin/console lint:twig templates`	35, 209	Symfony-only, and assumes Twig at all
`bin/lint-markdown.sh` / `make lint-markdown`	119, 250, 255	No
`scripts/docs-only-change.sh`	116, 121, 259	No
`.github/workflows/ci.yml`	99, 209	Path is conventional but the job names it implies are not
`actionlint`, `.github/actionlint.yaml`	36, 43–58	Reasonable to keep — it is a real external tool, not a repo path

commands/audit-docs.md:36 cites composer test:coverage too, but as an example of a
command to verify, which is fine — it is illustrating a class, not instructing.

The fix, and the shape it should take

Soften the reference, keep the rule. The rule is almost always the valuable half and it is
usually already stated; it is only the worked example that is repo-bound. The pattern used for
the docs-only classifier in VCS.md (added alongside this issue) is the model:

State the rule so it stands alone — "docs-only means *.md, *.markdown and docs/**,
and nothing else".
Then: "where a repo ships a classifier, it decides — in this one that is
scripts/docs-only-change.sh", and say what a repo without one does instead.

Applied to the gate, that means VCS.md should defer to the consuming project's own
Quality gate table the way /vcs-check already does, rather than restating
someones.computer's commands as if they were universal.

What is not established

Whether any other project actually consumes this submodule yet. If someones.computer is
the only one, this is pre-emptive — worth doing before the second consumer rather than
after, but it is not breaking anything today. Nobody has checked.
Whether docs/Topics/Documentation-Conventions.md, frameworks/symfony/CLAUDE.md and
languages/php/CLAUDE.md have the same problem. Only VCS.md, README.md,
CLAUDE.md and commands/*.md were surveyed. The two scoped files may be entitled to
assume more, being framework- and language-specific — that is a judgement call this issue
does not make.

Done when

Every command and path in VCS.md either exists in any repo consuming this submodule,
or is introduced as an example of a rule stated independently of it
The quality-gate commands defer to the consuming project's own CLAUDE.md table, the
way commands/vcs-check.md already does, instead of restating one project's
README.md's Requirements on the consuming project is referenced from VCS.md, so
the convention is discoverable from the file that has to follow it
A reader of a repo that ships none of these scripts can still follow every rule in
VCS.md

Found while adding the Pure-docs PRs skip the draft exemption, which needed a docs-only
classifier and raised the question of what a project without one should do.

`VCS.md` names concrete scripts, Make targets and console commands that only exist in `someones.computer`. A project that consumes this submodule and doesn't happen to ship them gets a rule pointing at a path that isn't there — so the rule reads as broken and gets ignored, rather than applied in whatever form that project has. **The convention to follow already exists in this repo.** `README.md`, *Requirements on the consuming project*: > `vcs-check` and `ci-local` don't hardcode tool invocations — projects differ (host > `composer` vs. `docker compose exec <service> ...`; PHPUnit-only vs. > PHPUnit+PHPStan+php-cs-fixer). Instead they read the consuming project's own root > `CLAUDE.md` for a "Quality gate" table. `commands/vcs-check.md` and `commands/ci-local.md` were written to that rule and are described in `README.md` as "generic by design". `VCS.md` was not, and is now the odd one out. ## What is established Surveyed against `a90d415`, every `*.md` in this repo: | Reference in `VCS.md` | Line(s) | Exists everywhere? | |---|---|---| | `composer test:coverage` | 32, 39, 65, 209, 233 | No — assumes ParaTest **and** a 100% gate | | `bin/coverage-gate.php` | 40 | No — someones.computer's own script | | `php bin/console lint:yaml config --parse-tags` | 34, 209 | Symfony-only, and assumes `config/` | | `php bin/console lint:twig templates` | 35, 209 | Symfony-only, and assumes Twig at all | | `bin/lint-markdown.sh` / `make lint-markdown` | 119, 250, 255 | No | | `scripts/docs-only-change.sh` | 116, 121, 259 | No | | `.github/workflows/ci.yml` | 99, 209 | Path is conventional but the *job names* it implies are not | | `actionlint`, `.github/actionlint.yaml` | 36, 43–58 | Reasonable to keep — it is a real external tool, not a repo path | `commands/audit-docs.md:36` cites `composer test:coverage` too, but as an *example of a command to verify*, which is fine — it is illustrating a class, not instructing. ## The fix, and the shape it should take **Soften the reference, keep the rule.** The rule is almost always the valuable half and it is usually already stated; it is only the worked example that is repo-bound. The pattern used for the docs-only classifier in `VCS.md` (added alongside this issue) is the model: - State the rule so it stands alone — *"docs-only means `*.md`, `*.markdown` and `docs/**`, and nothing else"*. - Then: *"where a repo ships a classifier, it decides — in this one that is `scripts/docs-only-change.sh`"*, and say what a repo without one does instead. Applied to the gate, that means `VCS.md` should defer to the consuming project's own *Quality gate* table the way `/vcs-check` already does, rather than restating someones.computer's commands as if they were universal. ## What is *not* established - **Whether any other project actually consumes this submodule yet.** If someones.computer is the only one, this is pre-emptive — worth doing before the second consumer rather than after, but it is not breaking anything today. Nobody has checked. - **Whether `docs/Topics/Documentation-Conventions.md`, `frameworks/symfony/CLAUDE.md` and `languages/php/CLAUDE.md` have the same problem.** Only `VCS.md`, `README.md`, `CLAUDE.md` and `commands/*.md` were surveyed. The two scoped files may be entitled to assume more, being framework- and language-specific — that is a judgement call this issue does not make. ## Done when - [ ] Every command and path in `VCS.md` either exists in any repo consuming this submodule, or is introduced as an example of a rule stated independently of it - [ ] The quality-gate commands defer to the consuming project's own `CLAUDE.md` table, the way `commands/vcs-check.md` already does, instead of restating one project's - [ ] `README.md`'s *Requirements on the consuming project* is referenced from `VCS.md`, so the convention is discoverable from the file that has to follow it - [ ] A reader of a repo that ships none of these scripts can still follow every rule in `VCS.md` Found while adding the *Pure-docs PRs skip the draft* exemption, which needed a docs-only classifier and raised the question of what a project without one should do.

geusebio referenced this issue from a commit

2026-08-07 10:32:17 +00:00

Let a pure-docs PR skip the draft, and stop [skip ci] stranding one

geusebio referenced this issue

2026-08-07 10:32:42 +00:00

Let a pure-docs PR skip the draft, and stop [skip ci] stranding one #11