From 507a557a749f53d5427b798a9a26c55bf53bdc8e Mon Sep 17 00:00:00 2001 From: Sergio Sisternes Date: Thu, 18 Jun 2026 19:41:39 +0100 Subject: [PATCH] docs: restore "What to commit" guidance lost in #1252 The quickstart rewrite in PR #1252 dropped the commit/gitignore guidance that was added in PR #290 (issue #288). The only surviving copy was buried in an agent skill file, not user-facing docs. Add a "What to commit" section to quickstart.mdx (table + rationale for committing deployed files + CI drift check tip) and a matching note in consumer/install-packages.md that cross-links to it. Closes #1837 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../content/docs/consumer/install-packages.md | 13 +++++++++++++ docs/src/content/docs/quickstart.mdx | 18 ++++++++++++++++++ 2 files changed, 31 insertions(+) diff --git a/docs/src/content/docs/consumer/install-packages.md b/docs/src/content/docs/consumer/install-packages.md index e87dd8963..9f3e6bf83 100644 --- a/docs/src/content/docs/consumer/install-packages.md +++ b/docs/src/content/docs/consumer/install-packages.md @@ -124,6 +124,19 @@ harness, see [Primitives and targets](../../concepts/primitives-and-targets/). Rule sync to Cursor (`.cursor/rules/`), Claude Code (`.claude/rules/`), Windsurf (`.windsurf/rules/`), and Kiro (`.kiro/steering/`) is automatic and idempotent -- re-running `apm install` adopts unchanged rules without rewriting them. +## What to commit + +Commit `apm.yml`, `apm.lock.yaml`, and every harness directory APM writes to +(`.github/`, `.claude/`, `.cursor/`, `.opencode/`, `.gemini/`, `.windsurf/`, +`.kiro/`). Committed deployed files give teammates and cloud Copilot instant agent +context on clone, before they run `apm install`. + +Add `apm_modules/` to `.gitignore` -- it is the package cache and is rebuilt from +the lockfile on every `apm install`. APM adds the entry automatically on first install. + +See the [Quickstart](../../quickstart/#what-to-commit) for the full table and +rationale. + ## Transitive dependencies and the lockfile `apm install` resolves the full dependency graph, not just your diff --git a/docs/src/content/docs/quickstart.mdx b/docs/src/content/docs/quickstart.mdx index 1f02a3806..68a60ad13 100644 --- a/docs/src/content/docs/quickstart.mdx +++ b/docs/src/content/docs/quickstart.mdx @@ -148,6 +148,24 @@ For private packages, set `GITHUB_APM_PAT` -- see [private packages](/apm/consumer/private-and-org-packages/). ::: +## What to commit + +After `apm install` runs, three categories of files land in your project: + +| Path | Commit? | Why | +|------|---------|-----| +| `apm.yml` | Yes | Manifest -- declares dependencies, shared with the team | +| `apm.lock.yaml` | Yes | Lockfile -- pins exact commits and content hashes for reproducible installs | +| `.github/`, `.claude/`, `.cursor/`, `.opencode/`, `.gemini/`, `.windsurf/`, `.kiro/` | Yes | Deployed agent context -- gives every contributor and cloud Copilot instant access on clone, before they run `apm install` | +| `apm_modules/` | No | Package cache -- rebuilt from the lockfile on `apm install`. Add to `.gitignore` (APM does this automatically) | + +:::tip[Keeping deployed files in sync] +When you update `apm.yml`, re-run `apm install` and commit the changed deployed files +alongside the updated manifest and lockfile. A +[CI drift check](../integrations/ci-cd/#verify-deployed-primitives) catches stale +files automatically. +::: + ## What next Your project is ready: dependencies pinned, primitives deployed, every