[docs] Update dependencies guide for apm outdated and apm view versions (from #613)#634
[docs] Update dependencies guide for apm outdated and apm view versions (from #613)#634danielmeppiel wants to merge 1 commit intomainfrom
Conversation
Document apm outdated and apm view <pkg> versions in the dependencies guide (guides/dependencies.md). These commands were shipped in #613 but were only referenced in the CLI reference (cli-commands.md); the guide had no mention of how to check for staleness before running an update. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
danielmeppiel
added
automation
documentation
danielmeppiel
added
documentation
There was a problem hiding this comment.
Pull request overview
Updates the user-facing dependencies guide to document recently added dependency staleness detection features, aligning the workflow guide with the existing CLI reference for apm outdated and apm view ... versions.
Changes:
- Added a new “Checking for Outdated Dependencies” subsection documenting
apm outdatedusage and output columns. - Added a note on using
apm view OWNER/REPO versionsto inspect available remote refs before updating.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/guides/dependencies.md | Adds guidance for checking dependency staleness via apm outdated and inspecting remote refs via apm view ... versions. |
Copilot's findings
- Files reviewed: 1/1 changed files
- Comments generated: 2
| - **Latest** - the newest remote tag or branch-tip SHA | ||
| - **Status** - `up-to-date`, `outdated`, or `unknown` | ||
|
|
||
| Tag-pinned deps use semver comparison; branch-pinned deps compare commit SHAs. Local and Artifactory dependencies are skipped. |
There was a problem hiding this comment.
This section implies apm outdated can compare any SHA-pinned dependency, but commit-hash pins are currently reported as unknown (since the tool cannot map an arbitrary commit hash to a remote branch tip). Consider documenting that unknown can occur for commit-pinned refs, and that deps with no explicit ref are checked against the default branch tip (shown as (default)).
| Tag-pinned deps use semver comparison; branch-pinned deps compare commit SHAs. Local and Artifactory dependencies are skipped. | |
| Tag-pinned deps use semver comparison, and branch-pinned deps compare against the latest commit on that branch. Commit-pinned refs can show `unknown` because `apm outdated` cannot map an arbitrary commit SHA to a remote branch tip. Dependencies with no explicit ref are checked against the default branch tip and shown as `(default)`. Local and Artifactory dependencies are skipped. |
| ```bash | ||
| apm view owner/repo-name versions | ||
| ``` | ||
|
|
There was a problem hiding this comment.
apm view ... versions parses the package argument as a dependency reference and requires an owner/repo (or full URL) format; the short-name form used elsewhere in this guide only works for locally installed package metadata. Consider changing the example (or adding a short note) so readers don't try apm view repo-name versions and hit an "Invalid repository format" error.
| Use the dependency reference from `apm.yml` here (`owner/repo` or a full URL). A short package name alone is only valid for local installed-package metadata and will fail with an invalid repository format error. |
Documentation Updates - 2026-04-09
This PR updates the dependencies guide based on features merged in the last 24 hours.
Features Documented
apm outdatedcommand (from feat: add apm info, apm outdated, and list_remote_refs #613) - added to the dependencies workflow guideapm view (package) versionsfield (from feat: add apm info, apm outdated, and list_remote_refs #613) - referenced as a complement toapm outdatedChanges Made
docs/src/content/docs/guides/dependencies.mdto add a new "Checking for Outdated Dependencies" subsection just before the existing "Updating Dependencies" section.The new subsection documents:
apm outdatedusage with all options (--global,--verbose,-j N)Package,Current,Latest,Status)apm view owner/repo-name versionsas a complement for inspecting available refs before updatingMerged PRs Referenced
Notes
The CLI reference (
docs/src/content/docs/reference/cli-commands.md) and the skill guide (packages/apm-guide/.apm/skills/apm-usage/commands.md) already documented both commands. The CHANGELOG for[0.8.11]also covered the changes. The only gap was the user-facing dependencies guide, which described the update workflow but gave no visibility into staleness detection before updating.