docs: restore "What to commit" guidance (fix #1837)#1839
Merged
danielmeppiel merged 1 commit intoJun 19, 2026
Conversation
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>
Contributor
There was a problem hiding this comment.
Pull request overview
Restores missing end-user documentation on what files to commit vs gitignore after running apm install, reintroducing guidance that was lost during the docs rewrite and making it discoverable both from the quickstart and the consumer install guide.
Changes:
- Added a “What to commit” section (with a table) to
quickstart.mdx. - Added a concise “What to commit” section to
consumer/install-packages.md, linking back to the quickstart table.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/src/content/docs/quickstart.mdx | Adds the restored “What to commit” table + drift-check tip in the quickstart flow. |
| docs/src/content/docs/consumer/install-packages.md | Adds a parallel “What to commit” section for readers who start from the consumer install guide, with a cross-link to quickstart. |
|
|
||
| ## What to commit | ||
|
|
||
| After `apm install` runs, three categories of files land in your project: |
| |------|---------|-----| | ||
| | `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` | |
Comment on lines
+129
to
+132
| 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`. |
danielmeppiel
approved these changes
Jun 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The "What to commit / What to gitignore" guidance was added in PR #290 (issue #288) to the old quickstart. The full docs rewrite in PR #1252 replaced the quickstart file and the section was lost entirely. The only surviving copy is in an agent skill (
packages/apm-guide/.apm/skills/apm-usage/workflow.md), which is not user-facing.Closes #1837
Changes
docs/src/content/docs/quickstart.mdxAdded a new "What to commit" section between the install output block and "What next". Includes:
apm.ymlandapm.lock.yaml(commit), deployed harness dirs.github//.claude//.cursor// etc. (commit),apm_modules/(gitignore)docs/src/content/docs/consumer/install-packages.mdAdded a concise "What to commit" section after "Where files land" for users who navigate directly to the consumer guide. Cross-links to the quickstart table.
No code changes
Documentation only. No CLI, schema, or behaviour changes.