docs: progressive-disclosure docs (generated reference, per-feature folders, slim README/CHANGELOG/CLAUDE.md) - #29
Merged
Merged
Conversation
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
- CHANGELOG.md keeps [Unreleased] + 0.18.x; 0.17, 0.16 and 0.1 move unchanged to docs/changelog/<minor>.md (no lines lost) - scripts/changelog-rollover.py runs from promote-changelog.sh so each new minor release rolls the previous one off automatically - scripts/check-docs.py reports broken links, size budgets, missing descriptions and changelog bullet length (report-only for now) - rename docs/desgin.md to docs/design.md; fix 7 broken links Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
docs/commands.md is generated from `asc --experimental-dump-help` with plugins disabled; docs/README.md is generated from feature doc frontmatter. Neither is edited by hand. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
README keeps the pitch, quick start, CAEOAS example and a feature table that links to each feature doc (744 -> 97 lines). The hand-written command reference is replaced by docs/commands.md; the release workflow, Swift package guide and development notes move to docs/release.md, docs/library.md and CONTRIBUTING.md. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Moves every feature doc into its own folder, shaped like a Skill, so a feature always has one path and deep dives are added next to README.md without moving anything. Link targets rewritten mechanically; no content changes. check-docs reports zero broken links. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Each docs/features/<x>/README.md now has a description and follows Quick start -> Workflows -> REST -> Gotchas -> See also, within 200 lines (17,661 -> 3,854 lines total). Flag tables are replaced by links to the generated command reference; architecture, domain model, file map, testing and extending sections are removed, with non-obvious reasons kept as gotchas. Contributor design docs (command center, web server, web apps, web console, screenshot editor) move unchanged to design.md next to their README. Also stops the generator dropping real --version options and the `asc version` command. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
CLAUDE.md keeps the TDD gate, commands, layer rules and pointers (286 -> 76 lines). The REST exposure checklist and doc rules move into the implement-feature skill, which loads only when building a feature; the domain folder tree is dropped since the source tree shows it. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
|
Important Review skippedToo many files! This PR contains 124 files, which is 24 over the limit of 100. To get a review, reduce the PR to 100 files or fewer by splitting it into smaller PRs or changing its base branch. Upgrade to a paid plan to raise the limit. This review couldn't start because sufficient usage credits or metered capacity aren't available. Add credits or update usage-based reviews in the billing tab, then retry. ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Advanced Run ID: 📒 Files selected for processing (124)
You can disable this status message by setting the Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
- iap-subscriptions/pricing.md linked to the parent README's old #rest-endpoints section, now #rest - CONTRIBUTING pointed new features at docs/features/<x>.md - documentation design now describes the per-feature design.md files the migration created Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…fter rollover When a new minor was released, the rollover left the new version as the last section in CHANGELOG.md, so: - extract-changelog.sh read on into the 'Older releases' line and the reference links, and those would land in the GitHub Release notes - the empty-release fallback in release.yml waited for a '---' that the rollover had removed, so no entry was written extract-changelog.sh now stops at any heading, separator or reference link. The fallback moves from release.yml into promote-changelog.sh and runs before the rollover. scripts/test-changelog-release.sh runs the release sequence for patch and minor releases, with and without entries, and runs in CI. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
A source-level review of every feature doc found claims that didn't match the code. Fixed: - wrong web-server port in curl examples (8420, not 5173/8080); the server binds 0.0.0.0, so the loopback advice was impossible - plugin install/uninstall REST examples used names that can't match - reports --version example (1_4), missing --version on builds upload, a non-existent `asc versions get` in a workflow step, jq path for reviews output, market affordance key (browseMarket) - incomplete affordance lists in JSON samples (review submissions, app infos), IAP submit conditions, promoted-purchase create default, primary-locale rule in check-readiness, CLI delete for app-info localizations, skills update/check behaviour (the background update checker is not wired into any command) - library.md example didn't compile (bundleId, listBuilds signature); macOS minimum is 14 per Package.swift Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
- iris session order: saved Apple ID login first, then ASC_IRIS_COOKIES, then browser cookies; --platforms takes one value per flag; verify-code prints JSON; status sample gains submitIAP - iris-srp-login: --method and --trust were planned, not implemented - remaining 8080 ports -> 8420; screenshot editor exports screenshots.zip; import also reads order - app-wall: developer is optional, duplicate and fork-timeout behaviour - performance: --build-id wins when both ids are given - command center is hosted at cc.asccli.app, not served by web-server - submission-iris-parity referred to a non-existent `asc iap get` Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #29 +/- ##
==========================================
- Coverage 82.04% 82.04% -0.01%
==========================================
Files 492 492
Lines 14362 14362
==========================================
- Hits 11784 11783 -1
- Misses 2578 2579 +1 🚀 New features to boost your workflow:
|
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.
Why
Docs grew with every feature: the doc rules made each feature copy the same facts into the README list, the README command examples, a 9-section feature doc and a long changelog bullet. Nothing removed content and nothing checked it.
This PR restructures the docs around one goal: reduce accidental complexity so docs are easy to change. Docs now load in tiers, like Agent Skills: a small top level that links down, never copies. The full design is in
docs/documentation-design/README.md.What changed
README.mdCHANGELOG.mddocs/changelog/, moved unchanged)CLAUDE.mdmake docswritesdocs/commands.mdfromasc --experimental-dump-help(plugins off) anddocs/README.mdfrom each feature's frontmatterdescription. Neither is edited by hand.docs/features/<x>/README.mdholds the user guide (≤200 lines): Quick start, Workflows, REST, Gotchas, See also. Deep dives sit next to it. There are no flag tables (the generated reference has them) and no architecture, domain model, file map or testing sections (the source has them).design.mdnext to a short README.docs/release.md,docs/library.mdandCONTRIBUTING.md.scripts/changelog-rollover.pyruns frompromote-changelog.sh, so each new minor release moves the previous one intodocs/changelog/<minor>.md. New entries are one line each, with a doc link and a PR link, and the[Unreleased]entries are condensed to that style.implement-featureskill.Docsjob runsscripts/check-docs.py --strict: links, size budgets, descriptions, changelog bullet length and the one-minor rule.Also in this PR
Release script fix. When a new minor was released, the rollover left the new version as the last section of
CHANGELOG.md, which broke two things:extract-changelog.shread on into "Older releases" and the reference links, so those would have landed in the GitHub Release notes.extract-changelog.shnow stops at any heading, separator or reference link, and the fallback moved intopromote-changelog.sh, before the rollover.scripts/test-changelog-release.shruns the release sequence for patch and minor releases, with and without entries, and runs in CI. It fails 8 checks against the old scripts.Source-level fact check. Every feature doc was checked against
Sources/, and wrong claims were fixed:library.mdhad Swift code that didn't compileCode issues found (not fixed here, since they need tests first)
getVersionon review submission items and submission plans points atasc versions get, which doesn't exist.GET /api/v1advertisesbetaAppLocalizationsat/api/v1/beta-app-localizations, but no route serves it.createAvailabilityresolves toPOST /api/v1/iap/{id}/availability, but the controller only registersPATCH.update,deleteandcreateIntroductoryOfferlinks have no REST route.SkillUpdateChecker.checkIfNeededis never called.POST /api/v1/subscriptions/:id/prices, but the route is/prices/set-batch.Review notes
builds archivedefault isapp-store-connect.version-check-readinesssaid pricing needed the web UI;asc apps prices setexists now.performance,init,asc-users,game-centerandskillshave no REST routes.web-apps/design.md(it describes a Node.js proxy) andasc-web-management/design.md(it describes anasc webcommand that no longer exists) were moved as they were. Both are candidates for deletion.skills/submodule. Itsasc-cli/references/commands.mdshould link todocs/commands.mdin a follow-up.Test plan
python3 scripts/check-docs.py --strictshows 0 problemsmake docsregenerates with no diffpromote-changelog.sh 0.19.0rolls 0.18.x intodocs/changelog/0.18.mdextract-changelog.shstill returns the notes for released versions and for[Unreleased]scripts/test-changelog-release.shpasses (patch and minor, with and without entries)asccommand, flag, REST path and anchor in the docs exists in the binary, the controllers or the target file🤖 Generated with Claude Code