docs(compile): document targets: to pin the committed generated set (#1342) by danielmeppiel · Pull Request #1583 · microsoft/apm

danielmeppiel · 2026-06-02T12:25:52Z

Description

Documents how to make apm compile output deterministic for repos that commit generated artifacts by explicitly setting targets: in apm.yml, rather than relying on auto-detection from locally-present harness folders.

What this resolves: Issue #1342 originally proposed three code changes (.gitignore coverage, an apm add-vcsignore command, and compile-refuse-overwrite). The maintainer rejected all three code changes and approved the docs-only resolution. This PR implements exactly that maintainer-endorsed scope.

The problem documented: When teams commit the files apm compile generates (AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md) without setting targets: in apm.yml, auto-detection governs which files are produced. A contributor with only .claude/ locally produces claude output only; a developer who also has .github/ triggers the two-or-more-folders rule and gets the full all expansion. The committed set silently tracks whoever last ran apm compile.

The fix documented: Set targets: in apm.yml (preferred spelling per manifest-schema 3.6) to declare exactly which agent formats the project supports:

targets: [claude, cursor]   # compile writes exactly these two sets; nothing else

Every invocation of apm compile -- local developer, CI, cloud agent -- then writes the same files regardless of which tool folders exist on that machine.

Pages changed:

docs/src/content/docs/reference/cli/compile.md -- new "Pin committed output with targets:" section placed after Options (before Examples), with corrected file list (AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md only -- apm install outputs excluded) and corrected auto-detect behavior (≥2 folders → all, not a union of detected targets)
docs/src/content/docs/reference/manifest-schema.md -- "Deterministic committed output" guidance upgraded to a Starlight :::tip admonition in section 3.6, with cross-link updated to match renamed section heading
docs/src/content/docs/getting-started/first-package.md -- breadcrumb added in step 4's apm compile callout pointing users to the pinning guidance before they hit the committed-set consistency pain

No source code (src/) changes.

Docs build validation:

[build] 112 page(s) built in 24.64s
All internal links are valid.
[build] Complete!

Type of change

Bug fix
New feature
Documentation
Maintenance / refactor

Testing

Tested locally
All existing tests pass
Added tests for new functionality (if applicable)

Spec conformance (OpenAPM v0.1)

N/A -- this PR does not change OpenAPM-observable behaviour.

…1342) Adds a 'Pinning the committed generated set' section to the apm compile reference page explaining that omitting target: in apm.yml causes the committed generated files to silently track whoever last ran apm compile. The recommended fix -- set target: [claude, cursor] (or whichever agents the team uses) -- is now documented with a concrete example. Also adds a 'Deterministic committed output' callout to the manifest-schema target: section (3.6) with a cross-link to the new compile section. No source code changes. Maintainer-endorsed docs-only resolution of #1342. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Documents how to make apm compile output deterministic for repos that commit generated artifacts by explicitly setting target:/targets: in apm.yml, rather than relying on auto-detection from locally-present harness folders.

Changes:

Adds a "Pinning the committed generated set" section to the apm compile reference page describing the drift problem and the recommended configuration.
Adds a "Deterministic committed output" callout to the manifest schema target field reference, linking back to the compile documentation.

Show a summary per file

File	Description
docs/src/content/docs/reference/cli/compile.md	Adds guidance on pinning generated outputs by setting `target:`/`targets:`.
docs/src/content/docs/reference/manifest-schema.md	Adds a callout explaining why explicit target selection is needed for deterministic committed artifacts.

Copilot's findings

Files reviewed: 2/2 changed files
Comments generated: 2

+`apm compile` generates derived files: `AGENTS.md`, `CLAUDE.md`,
+`.claude/commands/`, `.cursor/rules/`, `.github/copilot-instructions.md`,
+`.agents/`, and similar. Teams that commit these files into source
+control face a consistency problem: without `target:` set in `apm.yml`,
+auto-detection decides which files to produce based on which tool folders
+exist on the current machine. A developer with `.github/` and `.claude/`
+locally produces `copilot` + `claude` output; a contributor with only
+`.claude/` produces `claude` output only. The committed set silently
+tracks whoever last ran `apm compile`.
+
+Set `target:` in `apm.yml` to declare exactly which agent formats the
+project supports. Every run of `apm compile` -- local developer, CI,
+cloud agent -- then writes the same files regardless of which tool
+folders exist on that machine:
+
+```yaml
+# apm.yml
+target: [claude, cursor]   # compile writes exactly these two sets; nothing else
+```
+
+This makes the committed generated files deterministic for humans,
+cloud agents, and contributors who do not run `apm compile` locally
+and rely on the checked-in artifacts.


+**Deterministic committed output.** Teams that commit the files `apm compile`
+generates face a consistency problem: without `target:` set, auto-detection
+decides which files to produce based on which tool folders exist on the local
+machine. The committed set silently tracks whoever last ran `apm compile`.
+Setting `target:` makes the output deterministic for every developer, CI
+runner, and cloud agent that relies on the checked-in generated files without
+running `apm compile` locally. See
+[Pinning the committed generated set](./cli/compile/#pinning-the-committed-generated-set).


…ng section - Correct the auto-detect example: two or more detected tool folders resolve to 'all' (not a copilot+claude union); single folder resolves to that one target only - Remove .claude/commands/, .cursor/rules/, .agents/ from the compile output list -- those are apm install outputs; compile writes only root context files (AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md) - Switch example from target: to targets: (the preferred spelling per manifest-schema 3.6 guidance) - Add cross-reference to Output layout per target table Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

danielmeppiel · 2026-06-02T12:51:05Z

APM Review Panel Advisory

PR: docs(compile): document target: to pin the committed generated set (#1342)
Panel run: shepherd-driver iteration 1 -- docs-only PR
Active panelists: python-architect, cli-logging-expert, devx-ux-expert, supply-chain-security-expert, oss-growth-hacker, doc-writer
Inactive: auth-expert (no auth surface), test-coverage-expert (no src/**/*.py changes)

CEO Synthesis: SHIP_WITH_FOLLOWUPS

The PR addresses a genuine discoverability gap and the content quality is good. Two blocking accuracy errors were found by the doc-writer panel and have already been folded into a follow-up commit (HEAD: 1449db6):

Auto-detect behavior corrected -- the original example claimed two detected tool folders produce a 'copilot + claude union'. In practice, detect_target returns 'all' (the full expanded set) when >=2 folders are present. The correction actually strengthens the PR's argument.
Compile output file list corrected -- the original listed .claude/commands/, .cursor/rules/, .agents/ as apm compile outputs. Per this same page's own Description and Output layout table, those are apm install outputs. Compile writes only root context files: AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md.
targets: preferred spelling applied -- example switched from target: (singular, legacy) to targets: (plural, recommended per manifest-schema 3.6).

Folded (applied in commit `1449db6`)

Panelist	Finding	Disposition
doc-writer	Auto-detect example wrong: 2+ folders -> all, not copilot+claude union	FOLDED
doc-writer	.claude/commands/, .cursor/rules/, .agents/ are apm install outputs, not apm compile	FOLDED
doc-writer	Example uses singular target:; schema prefers targets:	FOLDED

Deferred (recommended follow-ups, not blocking)

Panelist	Finding	Severity
devx-ux-expert	Section between Description and Options breaks CLI reference scan pattern; consider moving after Options	recommended
oss-growth-hacker	Getting-started/first-package.md has no breadcrumb to this guidance; users hit the pain before finding the fix	recommended
oss-growth-hacker	Section heading 'Pinning the committed generated set' is description-shaped; 'Pin committed output with targets:' would scan better in ToC	nit
cli-logging-expert	GEMINI.md not in illustrative paragraph (uses 'and similar' as catch-all; doc is correct but less complete)	nit
oss-growth-hacker	Manifest-schema callout could use a Starlight :::tip admonition for visual weight	nit

Security

supply-chain-security-expert: clean pass. Pinning targets: is a net supply-chain hygiene improvement -- it eliminates environment-dependent non-determinism in committed generated artifacts.

Ship decision: Advisory SHIP_WITH_FOLLOWUPS. The two blocking accuracy issues have been corrected in the follow-up commit. The deferred items are quality improvements suitable for a follow-on PR after merge.

danielmeppiel · 2026-06-02T13:12:38Z

@copilot act on the recommendations above from the last comment

- Rename section heading to 'Pin committed output with targets:' for better ToC scannability - Move pinning section after Options (before Examples) to follow CLI reference scan pattern - Replace bold-text callout in manifest-schema.md with Starlight :::tip admonition for visual weight - Update link anchor in manifest-schema.md to match renamed heading - Add breadcrumb in first-package.md step 4 pointing to pinning guidance - Expand 'all' expansion description to explicitly name all root context files (GEMINI.md etc.) Co-authored-by: danielmeppiel <51440732+danielmeppiel@users.noreply.github.com>

Copilot · 2026-06-02T13:18:47Z

@copilot act on the recommendations above from the last comment

All five deferred recommendations folded in the latest commit:

Section heading renamed — Pinning the committed generated set → Pin committed output with targets: (scans better in ToC)
Section moved after Options — now sits between the Modes table and Examples, following the CLI reference scan pattern
Manifest-schema callout upgraded — replaced the bold-text paragraph with a Starlight :::tip[Deterministic committed output] admonition for visual weight; anchor link updated to match the new heading
Breadcrumb added in first-package.md — the existing apm compile callout in step 4 now ends with a sentence pointing to the pinning section
all expansion made explicit — replaced the "and every other target" catch-all with the full file list (AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md)

Docs build: 112 pages, all internal links valid.

Copilot AI review requested due to automatic review settings June 2, 2026 12:25

danielmeppiel requested a review from sergio-sisternes-epam as a code owner June 2, 2026 12:25

Copilot started reviewing on behalf of danielmeppiel June 2, 2026 12:26 View session

danielmeppiel self-assigned this Jun 2, 2026

danielmeppiel added the status/shepherding Actively being driven by an APM shepherd run label Jun 2, 2026

Copilot AI reviewed Jun 2, 2026

View reviewed changes

danielmeppiel removed the status/shepherding Actively being driven by an APM shepherd run label Jun 2, 2026

Copilot started work on behalf of danielmeppiel June 2, 2026 13:12 View session

Copilot AI changed the title ~~docs(compile): document target: to pin the committed generated set (#1342)~~ docs(compile): document targets: to pin the committed generated set (#1342) Jun 2, 2026

Copilot finished work on behalf of danielmeppiel June 2, 2026 13:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(compile): document targets: to pin the committed generated set (#1342)#1583

docs(compile): document targets: to pin the committed generated set (#1342)#1583
danielmeppiel wants to merge 3 commits into
mainfrom
danielmeppiel/1342-target-docs

danielmeppiel commented Jun 2, 2026 •

edited by Copilot AI

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

danielmeppiel commented Jun 2, 2026

Uh oh!

danielmeppiel commented Jun 2, 2026

Uh oh!

Copilot AI commented Jun 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

danielmeppiel commented Jun 2, 2026 • edited by Copilot AI Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

Testing

Spec conformance (OpenAPM v0.1)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

danielmeppiel commented Jun 2, 2026

APM Review Panel Advisory

CEO Synthesis: SHIP_WITH_FOLLOWUPS

Folded (applied in commit 1449db6)

Deferred (recommended follow-ups, not blocking)

Security

Uh oh!

danielmeppiel commented Jun 2, 2026

Uh oh!

Copilot AI commented Jun 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

danielmeppiel commented Jun 2, 2026 •

edited by Copilot AI

Loading

Folded (applied in commit `1449db6`)