Skip to content

docs: restore "What to commit" guidance (fix #1837) #1839

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
danielmeppiel merged 1 commit into from
Jun 19, 2026
Merged

docs: restore "What to commit" guidance (fix #1837) #1839

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/src/content/docs/consumer/install-packages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Comment on lines +129 to +132

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
Expand Down
18 changes: 18 additions & 0 deletions docs/src/content/docs/quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading