Skip to content

feat: accept documentation proposals from anyone - #291

Merged
carlok merged 2 commits into
mainfrom
maintenance/docs-only-path
Sep 23, 2026
Merged

carlok merged 2 commits into
mainfrom
maintenance/docs-only-path

Conversation

@carlok

@carlok carlok commented Sep 23, 2026

Copy link
Copy Markdown
Owner

Closes the friction #290 documented. Twice now, @qazW12345 has tried to improve docs/CONTRIBUTION-DIRECTIONS.md and been refused by the receiver: an ordinary submission may change only LeanFrontier/ plus one claim, and the maintenance/ path is gated on OWNER, so a fork cannot propose prose at all. Both times a maintainer cherry-picked the commit instead (#200, #290).

The rule

A pull request whose every changed path is a Markdown file under docs/ is a documentation proposal: no claim, no Lean, no build.

  • Decided from the changed paths, never from the branch name, keeping the project's own rule that a branch name grants nothing.
  • docs/catalogue/ and docs/website/ are excluded. The first is generated from the corpus; the second is deployed to Pages, so a change there would publish under the project's name.
  • Size limits still apply, deletions are still refused, and a mixed change (docs plus anything else) is an ordinary submission and fails as one.
  • Nothing merges unattended: no mechanical check reads prose, so a person still reads it.

Workflow

The preflight now reports docs_only, and the three stages that build or run candidate code are gated on it:

stage gated
Build trusted validation image yes
Fetch pinned dependencies and Mathlib cache yes
Restricted formal validation yes

So a prose change costs one short job instead of a Docker build and a Mathlib fetch.

Evidence

  • End to end with the real receiver: a docs-only diff against main → accepted: True, docs_only: True, changed_files: ['docs/CONTRIBUTION-DIRECTIONS.md'], no diagnostics, no Lean run.
  • Tests (all failed before the change where they should): docs-only accepted without a claim; a new docs file accepted; docs mixed with Lean rejected; docs/website/ and docs/catalogue/ both rejected as path violations; a docs deletion rejected; and a workflow contract test pinning that each Lean stage carries the docs_only gate.

Full suite: 151 tests, 6 skipped.

CONTRACT.md §2 and CONTRIBUTING.md describe the new contribution type.

🤖 Generated with Claude Code

carlok and others added 2 commits September 23, 2026 14:09
A pull request changing only Markdown under docs/ is now admitted with
no claim, no Lean source and no build. Twice the one external
contributor tried to improve docs/CONTRIBUTION-DIRECTIONS.md and was
refused: an ordinary submission may only touch LeanFrontier/ plus one
claim, and the maintenance path requires OWNER, so a fork could not
propose prose at all. Both times a maintainer had to cherry-pick the
commit (#200, #290).

The receiver decides from the changed paths, never from the branch
name. docs/catalogue/ is generated from the corpus and docs/website/ is
published under the project's name, so neither counts as prose a
submitter may edit. Size limits still apply, deletions are still
refused, and a mixed change (docs plus anything else) is an ordinary
submission and fails as one.

In the workflow the preflight now reports docs_only, and the image
build, dependency fetch and restricted formal validation are gated on
it: no candidate code runs for a prose change. Nothing merges
unattended, because no mechanical check reads prose.

Verified end to end: the real receiver on a docs-only diff against main
returns accepted with docs_only true and no diagnostics.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@carlok
carlok merged commit 7004036 into main Sep 23, 2026
7 checks passed
@carlok
carlok deleted the maintenance/docs-only-path branch September 23, 2026 12:13
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