Skip to content

Improve AGENTS.md monorepo and PR-authoring guidance #1265

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
cristianrgreco merged 2 commits into from
Mar 10, 2026
+14 −2
Merged

Improve AGENTS.md monorepo and PR-authoring guidance #1265

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
96dace3
Document monorepo workflow and safe gh PR body handling
cristianrgreco Mar 10, 2026
98c21cd
Reorganize AGENTS guidance for monorepo and PR body safety
cristianrgreco Mar 10, 2026
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
16 changes: 14 additions & 2 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,16 @@
This is a working guide for contributors and coding agents in this repository.
It captures practical rules that prevent avoidable CI and PR churn.

## Repository Layout

- This repository is an npm workspaces monorepo.
- root package: `testcontainers-monorepo`
- workspaces: `packages/testcontainers` and `packages/modules/*`
- shared lockfile: root `package-lock.json` (workspace installs update this single file)
- For workspace-scoped dependency changes, prefer targeted commands to reduce lockfile churn:
- `npm install -w @testcontainers/<module>`
- `npm uninstall -w @testcontainers/<module> <package>`

## Development Expectations

- If a public API changes, update the relevant docs in the same PR.
Expand All @@ -21,7 +31,7 @@ It captures practical rules that prevent avoidable CI and PR churn.
## Permission and Escalation

- `npm install` requires escalated permissions for outbound network access to npm registries.
- `npm test` commands should b`e run with escalation so tests can access the Docker socket.
- `npm test` commands should be run with escalation so tests can access the Docker socket.

### Escalation hygiene

Expand All @@ -41,6 +51,8 @@ It captures practical rules that prevent avoidable CI and PR churn.
- If signing fails (for example, passphrase/key issues), stop and ask the user to resolve signing, then retry.
8. Push branch. Ask for explicit user permission before any force push.
9. Open PR against `main` using a human-readable title (no `feat(...)` / `fix(...)` prefixes).
- When using `gh` to create/edit PR descriptions, prefer `--body-file <path>` over inline `--body`.
- This avoids shell command substitution issues when the body contains backticks.
10. Add labels for both change type and semantic version impact.
11. Ensure PR body includes:
- summary of changes
Expand Down Expand Up @@ -73,6 +85,6 @@ It captures practical rules that prevent avoidable CI and PR churn.
- docs-only change: `documentation` + usually `patch`
- dependency update: `dependencies` + impact label based on user-facing effect

## Practical Note
## Lockfile Hygiene

- Recheck `package-lock.json` after `npm install` for unrelated drift and revert unrelated changes.
Loading