docs: trim the README, disclose the LLM assistance, fix the canonical URL - #11
Merged
Conversation
… URL The registry's LLM policy asks for two things this package did not do. **Disclose substantial generative-AI contribution in the README.** There was no disclosure at all. There is one now, and it separates what is the maintainer's from what is assisted. **"Avoid lengthy, verbose, and over-selling READMEs; review and trim down any documentation generated by an LLM."** Measured against comparable packages: ExperimentalAPI 1372 words -> 419 Documenter.jl 285 Aqua.jl 163 Everything cut has a home in the deployed docs, checked section by section: the Aqua argument, "what this is not", the audit's blind spots, release decisions and the declaring/querying walk are all already written in `docs/src/`. The README now carries the motivation, the example that runs, the one-line check, install, and links. The motivation paragraph is a translation of what the maintainer wrote himself, rather than an argument composed here — which is the practice the reviewer recommended: write it in Japanese, then have it translated. **The canonical URL was never fixed.** Reported in review, still pointing at `codes.sota-shimozono.com`, which does not resolve — measured, 000. Now the live host. Measured there too: `/` and `/dev/` return 200, `/stable/` returns 404 because `gh-pages` holds only `dev` until a version is tagged. `/stable/` is still the right target and the comment says why, rather than pointing `canonical` at a moving `/dev/`. Closes #3: the extension blind spot has a workaround this package already uses on `test_surface` — declare the function and its docstring in the parent, let the extension add only the method. Said next to the bullet, in both places the bullet appears. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
github-actions
Bot
added
the
documentation
Contributor
|
📚 Docs preview: https://codes.sota-shimozono.com/ExperimentalAPI.jl/previews/PR11/ (updates on each push to this PR) |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
sotashimozono
added a commit
that referenced
this pull request
Sep 5, 2026
`main` moved under this branch: #11 cut the README from 1372 words to 419 for the registry's LLM policy, and #12 replaced the four required matrix contexts with one aggregate. Three files conflicted, and the resolution is not "keep both halves" in any of them: * **README.md** — `main`'s trimmed version wins wholesale. Re-adding the long sections written here would undo the point of #11. What is added back is two things that are now *false* without them: `record` and `reach` did not exist when that README was written, and the closing line called `test/spec/` "the specification for the propagation and profiling work that is not built yet". 559 words, against the 1372 that #11 cut. * **src/audit.jl** and **docs/src/checking.md** — the extension blind spot has a workaround #11 documented (declare the function in the parent, let the extension add only the method) and a report this branch added (`Audit.extensions`). Both are true, so both are said. The "methods on other packages' functions" bullet keeps this branch's version, because it stopped being a blind spot. `docs/make.jl` and `.github/workflows/CI.yml` merged cleanly and correctly — #11's canonical URL with this branch's page list, and #12's `all-tests` job with this branch's corrected runtime comment. Verified after the merge: `test_readme.jl`, `test_dogfood.jl`, `test_audit.jl`, the formatter, and a full docs build. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This was referenced Sep 5, 2026
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
1 participant
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.
The registry's LLM policy asks for two things this package did not do, and one review item was still unfixed.
1. No disclosure of generative-AI contribution
There was none. There is now, and it separates what is the maintainer's from what is assisted.
2. The README was long, and the policy asks that it not be
Measured against comparable packages:
Everything cut has a home in the deployed docs — checked section by section, not assumed:
docs/src/index.mddocs/src/index.mddocs/src/checking.mddocs/src/releases.mddocs/src/declaring.md,api.mddocs/src/observing.mdThe motivation paragraph is a translation of what the maintainer wrote himself, not an argument composed here — the practice the reviewer recommended: write it in Japanese, then have it translated. The runnable example is unchanged and still executed by
test/test_readme.jl.3. The canonical URL was never fixed
Reported in review; still pointing at
codes.sota-shimozono.com, which does not resolve. Measured:/stable/404s becausegh-pagesholds onlydevuntil a version is tagged. It is still the right canonical target — it materialises on the first release, and/dev/is a moving target that should never be canonical. The comment inmake.jlrecords the measurement rather than leaving a reader to rediscover it.Closes #3
The extension blind spot has a workaround this package already uses on
test_surface: declare the function and its docstring in the parent, let the extension add only the method. Said next to the bullet, in both places the bullet appears.Suite: 540 pass, 149 broken, 0 failing.
🤖 Generated with Claude Code