docs: explain package source vs installed copies - #2599
docs: explain package source vs installed copies#2599Aryan Singh K. (aryansk) wants to merge 1 commit into
Conversation
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds new documentation clarifying the distinction between an APM package’s canonical source repository and the installed (materialized) consumer copy, with recommended workflows for authors and consumers.
Changes:
- Documented “source vs installed” package concepts and best practices (don’t edit/commit installed copies).
- Added a step-by-step recommended author/consumer workflow with an example
git:dependency. - Clarified guidance for authoring and consuming within the same repository, including testing recommendations.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| APM does not currently provide a live-link/development-install mode that keeps | ||
| an installed consumer copy synchronized with edits in the source checkout. If | ||
| you need immediate feedback while authoring, test from the source repository or | ||
| re-run the install/update workflow after changes. |
Sergio Sisternes (sergio-sisternes-epam)
added
the
panel-review
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (1)
docs/src/content/docs/producer/source-vs-installed.md:13
- The doc says
apm installstages dependencies underapm_modules/, but when users follow the section below about installing globally, the materialized tree lives under~/.apm/apm_modules/(user scope). Consider wording this as "under the install scope's apm_modules/ directory" and explicitly calling out both paths so readers can map what they see on disk.
- **The installed copy is materialized consumer content.** `apm install`
resolves the declared dependency and stages the pinned package under
`apm_modules/` before integrating its primitives into the selected targets.
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Python Architect | 0 | 0 | 1 | Documentation-only PR; the conceptual model accurately reflects APM's actual architecture. No architectural concerns. |
| CLI Logging Expert | 0 | 0 | 1 | No CLI source changes. Guide accurately describes apm install behavior conceptually. No blocking/recommended findings. |
| DevX UX Expert | 0 | 2 | 2 | Solid mental-model doc. node_modules analogy apt. A few cross-link and discoverability gaps. |
| Supply Chain Security Expert | 0 | 1 | 2 | Documentation-only change. Example uses pinned version tag (good). Page misses opportunity to warn about mutable refs and lockfile SHA. |
| OSS Growth Hacker | 0 | 1 | 2 | Solid friction-reducer. node_modules analogy lands well for JS audience. Misses contributor hook on live-link gap. |
| Auth Expert | -- | -- | -- | No auth surface touched; ship. |
| Doc Writer | 1 | 3 | 1 | New page is well-scoped but has two correctness issues: wrong dependency schema in code example, and page not wired into the sidebar. |
| Test Coverage Expert | -- | -- | -- | Documentation-only PR; no runtime code paths to defend. |
| Performance Expert | -- | -- | -- | No performance surface touched; ship. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Top 5 follow-ups
- [Doc Writer] (blocking-severity) Fix dependency schema in code example to use valid object form or string shorthand. -- Current snippet would fail at
apm install-- misleads authors at the highest-trust moment in the doc. - [Doc Writer] Register page in
astro.config.mjssidebar and add frontmattersidebar.order. -- Without sidebar wiring the page is invisible to browsing readers -- zero discoverability. - [Supply Chain Security Expert] Add one-liner noting tags are mutable; lockfile pins immutable commit SHA. -- Reinforces secure-by-default positioning at near-zero cost; prevents authors from trusting mutable refs in production.
- [DevX UX Expert] Add cross-links from quickstart and CLI reference into this page. -- Three panelists independently flagged the page as an island; inbound links are the minimum viable discoverability fix.
- [OSS Growth Hacker] Open tracked issue for live-link/dev-install mode; link from the "no live-link" disclosure. -- Converts a limitation disclosure into a contributor funnel -- captures frustrated authors at peak motivation.
Architecture
classDiagram
direction LR
class SourceRepository {
<<Canonical>>
+apm.yml
+primitives/
}
class ConsumerProject {
+apm.yml
+apm.lock.yaml
+apm_modules/
}
class DependencyReference {
<<ValueObject>>
+git str
+ref str
}
class ResolvedReference {
<<ValueObject>>
+commit_sha str
+tag str
}
class InstalledCopy {
<<Materialized>>
+primitives/
}
ConsumerProject *-- DependencyReference : declares in apm.yml
ConsumerProject *-- ResolvedReference : pins in apm.lock.yaml
ConsumerProject *-- InstalledCopy : stages in apm_modules/
DependencyReference ..> SourceRepository : points to
ResolvedReference ..> SourceRepository : resolved from
InstalledCopy ..> SourceRepository : materialized from
class InstalledCopy:::touched
class SourceRepository:::touched
classDef touched fill:#fff3b0,stroke:#d47600
flowchart TD
A[Author edits primitives in source repo] --> B[Consumer declares git: + ref: in apm.yml]
B --> C[apm install resolves dependency]
C --> D[NET: Clone/fetch from git remote]
D --> E[FS: Write resolved SHA to apm.lock.yaml]
E --> F[FS: Stage package into apm_modules/]
F --> G[FS: Integrate primitives into targets]
H[Source package updated] --> I[Update ref: in apm.yml]
I --> C
Recommendation
The page concept is correct and fills a real gap, but the dependency schema example is demonstrably wrong and would mislead authors. Fix the YAML snippet (mechanical, under 5 min), wire the page into the sidebar, and this is ready to ship. The remaining recommended items (lockfile SHA note, cross-links, live-link issue) can land in the same PR or as fast follow-ups at author discretion.
Full per-persona findings
Python Architect
- [nit] Example uses shorthand
git: acme/ai-primitivesbut doesn't clarify host resolution atdocs/src/content/docs/producer/source-vs-installed.md:35
The spec supports both clone URLs and shorthands for thegit:field. The example uses shorthand form without mentioning that host resolution depends on authentication configuration.
Suggested: Consider adding a brief note or link to the authentication docs explaining howacme/ai-primitivesresolves to a full clone URL.
CLI Logging Expert
- [nit] Step 4 vaguely says 'the appropriate update workflow' -- could name
apm update
The doc already namesapm installexplicitly in step 3. Step 4 hedges with 'appropriate update workflow' instead of namingapm update, which is the actual command.
Suggested: Replace 'or use the appropriate update workflow' with 'or runapm update' if that command exists and is stable, otherwise leave as-is.
DevX UX Expert
- [recommended] Missing cross-links to/from quick-start and CLI reference
A new user hitting confusion about source vs installed will not discover this page unless it's linked from the getting-started funnel (quick-start.md, first-package.md) or fromapm installin cli-commands.md.
Suggested: Add a short 'See also' callout in quick-start.md after the install step, and a reference link in theapm installsection of cli-commands.md pointing here. - [recommended] The 'no live-link mode' disclosure is buried at the bottom
Users coming from pip's editable installs or npm link will search for that capability first. Burying it in the last paragraph means they scan the whole page before learning it doesn't exist.
Suggested: Add a one-line tip/admonition after the bullet list stating the limitation upfront, linking to the detailed paragraph below. - [nit] node_modules analogy could name the key behavioral difference (apm.lock.yaml derivation)
- [nit] Consider a frontmatter sidebar position or category tag for discoverability
Supply Chain Security Expert
- [recommended] Add a note that tags are mutable and the lockfile pins the immutable commit SHA
A version tag likev1.4.0can be force-pushed to point at a different commit. Users should understand thatapm.lock.yamlrecords the resolved commit SHA, which is the actual integrity anchor.
Suggested: Add: 'Whileref: v1.4.0is recommended over branch names, tags are mutable. APM's lockfile (apm.lock.yaml) pins the resolved commit SHA, ensuring reproducible installs regardless of tag movement. Always commit your lockfile.' - [nit] Warn against using branch refs (e.g.
ref: main) in production - [nit] The 'do not edit installed copies' guidance could mention integrity verification
OSS Growth Hacker
- [recommended] Missing contributor hook on the live-link gap disclosure
This is the exact moment a frustrated author is most receptive to contributing. A one-line link to an issue converts frustration into engagement.
Suggested: Add: 'Want live-link support? Follow or contribute to issue #NNNN for the design discussion.' - [nit] Opening paragraph could lead with the pain, not the architecture
Suggested: Consider a one-line callout like: 'Edited a file underapm_modules/and lost your changes on the next install? This page explains why -- and the workflow that avoids it.' - [nit] No cross-link to quickstart or first-package guide
Auth Expert -- inactive
No auth files touched; the PR adds a documentation page only and does not change token management, credential resolution, or host classification.
Doc Writer
- [blocking] Code example uses the wrong dependency schema -- flat list under
dependencies:and shorthandowner/repoingit:field atdocs/src/content/docs/producer/source-vs-installed.md:32
manage-dependencies.mdshows the correct top-level key isdependencies.apm(a mapping, not a flat sequence). Thegit:object form takes a full URL (https://github.com/acme/ai-primitives) not anowner/reposhorthand. The snippet as written would fail atapm install.
Suggested: Replace with:Or use string shorthand:dependencies: apm: - git: https://github.com/acme/ai-primitives ref: v1.4.0
- acme/ai-primitives#v1.4.0(nogit:key needed for GitHub-hosted packages). - [recommended] Page is not registered in the sidebar (
astro.config.mjs) and will not appear in navigation
Suggested: Add{ label: 'Source vs installed', slug: 'producer/source-vs-installed' }to the producer items array. - [recommended] Frontmatter missing
sidebar.order-- non-deterministic ordering vs other producer pages
Suggested: Addsidebar: order: Nconsistent with intended placement. - [recommended] No outgoing or incoming cross-links -- page is an island
Suggested: Link to../../consumer/manage-dependencies/for the full dependency reference format; link to./repo-shapes/in the same-repo section; add entry toproducer/index.md. - [nit]
descriptionfrontmatter could be more concise for SEO
Test Coverage Expert -- inactive
Documentation-only PR -- no runtime code paths to defend.
Performance Expert -- inactive
Documentation-only PR; no performance-sensitive code paths touched.
This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.
Sergio Sisternes (sergio-sisternes-epam)
removed
the
panel-review
Closes #2183
Summary
Validation
main