[docs] Update documentation for features from 2026-05-18#1380
Closed
danielmeppiel wants to merge 1 commit into
Closed
[docs] Update documentation for features from 2026-05-18#1380danielmeppiel wants to merge 1 commit into
danielmeppiel wants to merge 1 commit into
Conversation
…versioning schema - Add --check-versions and --check-clean flags to apm pack reference - Add exit codes 3 and 4 for the new release gates - Update --json envelope description to include new version_alignment and drift keys - Add release gates CI examples and versioning strategy config snippet - Add marketplace.versioning section (7.7) to manifest-schema.md covering lockstep / tag_pattern / per_package strategies Triggered by #1365 (feat(pack): add --check-versions and --check-clean release gates) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
danielmeppiel
added
automation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the reference documentation to cover newly added apm pack release-gate flags and the marketplace.versioning manifest schema block introduced in recent feature work (notably #1365).
Changes:
- Documented
apm pack --check-versions/--check-clean, their JSON envelope keys, and exit codes. - Extended the manifest schema reference to include
marketplace.versioningand described available strategies. - Added a CI-oriented “Release gates” usage section to the
apm packreference page.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/reference/cli/pack.md | Adds flag docs for release gates, JSON envelope notes, examples, and exit codes. |
| docs/src/content/docs/reference/manifest-schema.md | Documents the new marketplace.versioning schema entry and adds a dedicated section describing it. |
Copilot's findings
Comments suppressed due to low confidence (4)
docs/src/content/docs/reference/cli/pack.md:42
--check-cleanis described as regenerating into a temp directory and diffing against the committed copy, and as "never" writing to the working tree. In the current implementation, the drift gate compares regenerated JSON to the on-disk artifact, andapm packwill still write outputs unless--dry-runis used. Please adjust wording to match the behavior (and clarify that--dry-runis required if you want a pure "check" run).
| `--check-clean` | off | Regenerate `marketplace.json` into a temp directory and diff it against the committed copy. Exits `4` when any format has drifted. Never writes to the working tree. Composes with `--dry-run` and `--json`. |
docs/src/content/docs/reference/cli/pack.md:107
- In the CI examples,
apm pack --check-clean(and the combined--check-versions --check-clean --json) should likely also use--dry-run; otherwiseapm packmay rewrite marketplace artifacts before the drift check runs, which undermines the purpose of detecting drift and can dirty the workspace.
# Confirm committed marketplace.json is not stale (exits 4 on drift):
apm pack --check-clean
# Run both gates together; structured output for CI step summary:
apm pack --check-versions --check-clean --json
docs/src/content/docs/reference/cli/pack.md:118
- The strategy summary is not aligned with the
--check-versionsimplementation:tag_patternchecks for rendered tag collisions (it doesn't "check versions against build.tagPattern"), andper_packagestill fails if a local package is missing/invalidversion(it only relaxes cross-package equality). Please update this sentence to reflect the actual gate semantics.
Strategies: `lockstep` (default) -- all package versions match the top-level `version`; `tag_pattern` -- versions are checked against the `build.tagPattern`; `per_package` -- no cross-package version constraint (gate never fails).
docs/src/content/docs/reference/manifest-schema.md:678
- The strategy descriptions here don't match the implemented
--check-versionsbehavior.tag_patternusesbuild.tagPatternto render tags and fails on duplicate rendered tags across local packages;per_packagerelaxes cross-package equality but still fails when a local package has no/invalidversion(or missing apm.yml). Please update these rows so users understand what is actually enforced.
| `lockstep` | All packages listed under `marketplace.packages` MUST share the same `version` value as the top-level `version` field. The most common convention for monorepo marketplaces. |
| `tag_pattern` | Versions are derived from the `build.tagPattern` template; cross-package version equality is not enforced. Suitable for semantic-release workflows where each package tags independently. |
| `per_package` | No cross-package version constraint. The `--check-versions` gate always passes; the field documents intent without enforcement. |
- Files reviewed: 2/2 changed files
- Comments generated: 2
| | `-m`, `--marketplace FORMATS` | all configured | Comma-separated list of marketplace formats to build. Sentinels: `all` (every configured format), `none` (skip marketplace entirely). | | ||
| | `--marketplace-path FORMAT=PATH` | manifest default | Override the output path for a specific format. Repeatable. Example: `--marketplace-path codex=./dist/codex.json`. | | ||
| | `--json` | off | Emit machine-readable JSON to stdout. All logs move to stderr. Shape: `{ok, dry_run, warnings, errors, marketplace: {outputs: [...]}}`. | | ||
| | `--json` | off | Emit machine-readable JSON to stdout. All logs move to stderr. Shape: `{ok, dry_run, warnings, errors, marketplace: {outputs: [...]}, version_alignment, drift}`. The `version_alignment` and `drift` keys are always present; they are `null` when the corresponding gate flag was not passed. | |
Comment on lines
+666
to
+669
| | Field | Type | Required | Default | Description | | ||
| |---|---|---|---|---| | ||
| | `strategy` | `enum` | REQUIRED | `lockstep` | One of `lockstep`, `tag_pattern`, or `per_package`. | | ||
|
|
|
This pull request was automatically closed because it expired on 2026-05-21T06:13:48.972Z.
|
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.
Documentation Updates - 2026-05-18
This PR updates the documentation based on features merged in the last 24 hours.
Features Documented
apm pack --check-versionsand--check-cleanrelease gates (from feat(pack): add --check-versions and --check-clean release gates #1365)marketplace.versioningschema field (from feat(pack): add --check-versions and --check-clean release gates #1365)Changes Made
Updated
docs/src/content/docs/reference/cli/pack.md:--check-versionsflag: validates per-package versions againstmarketplace.versioning.strategy--check-cleanflag: regeneratesmarketplace.jsoninto a temp dir and diffs against the committed copy--jsonenvelope description to mention newversion_alignmentanddriftkeys3(version misalignment) and4(marketplace.json drift)marketplace.versioningconfig snippetUpdated
docs/src/content/docs/reference/manifest-schema.md:versioningrow to themarketplace:block fields table (Section 7.2)marketplace.versioning-- coverslockstep,tag_pattern, andper_packagestrategies with a full YAML exampleMerged PRs Referenced
feat(pack): add --check-versions and --check-clean release gatesapm plugin initnoun-verb surface #1370 -feat(cli): introduce apm plugin init noun-verb surface(docs shipped in the PR itself)feat(pack,doctor,init): vendor-neutral producer first-run UX(docs shipped in the PR itself)fix: add --target flag to apm update command(already reflected in update.md)apm uninstall#1325 -feat: support marketplace notation in apm uninstall(already reflected in uninstall.md)Notes
The following merged PRs were reviewed but required no documentation changes (either already documented by the PR author or internal/infrastructure changes):