docs: add PR guidelines and AI disclosure policy to AGENTS.md#15570
docs: add PR guidelines and AI disclosure policy to AGENTS.md#15570
Conversation
|
|
|
||
| - `feat:` → minor bump | ||
| - `fix:` → patch bump | ||
| - `docs:`, `chore:`, `refactor:` → usually no changeset needed |
There was a problem hiding this comment.
perhaps a section on major?
There was a problem hiding this comment.
Yeah, saying "don't"!
| ### AI Disclosure | ||
|
|
||
| If the PR was authored or co-authored using an AI tool (e.g. Claude, Copilot, Cursor, OpenCode), this **must** be disclosed in the PR description. Use one of the following labels: | ||
|
|
||
| - **`AI-generated`** — The contribution was primarily generated by an AI tool with human review. | ||
| - **`AI-assisted`** — A human wrote the contribution with help from AI tools (e.g. code completion, suggestions, debugging). | ||
|
|
||
| Include this as a line in the PR description, e.g.: | ||
|
|
||
| ``` | ||
| > AI-assisted: Co-authored using OpenCode (Claude) | ||
| ``` | ||
|
|
||
| or | ||
|
|
||
| ``` | ||
| > AI-generated: Generated by Claude with human review and testing | ||
| ``` | ||
|
|
||
| If a PR is `AI-generated`, it **must** be created as a draft (`gh pr create --draft`). The human controlling the agenty must manually review the changes and mark it as ready for review before it will be reviewed by the Astro team. |
There was a problem hiding this comment.
I'm not a heavy AI user, so maybe I'm wrong about the flow, but if I open an AI-TUI to ask a few questions or guide me through a PR, or do the same with ChatGPT in a tab of my browser, my PR is AI-assisted but I would never see this informations in this file I guess?
Shouldn't this be in the PR template or our CONTRIBUTING.md file?
|
The AI disclosure doesn't seem super helpful to me for a couple of reasons:
All the stuff about conventions and using the PR template, etc. I agree with, to be clear. |
|
|
||
| ## Changesets | ||
|
|
||
| This repo uses changesets. If your change affects published packages (features, fixes — not docs/chore), create a changeset. It will not trigger a release unless there is a changeset: |
There was a problem hiding this comment.
Actually, docs such as JsDocs should count as patches. That's what we've been doing
| 2. Make changes and commit using conventional commit messages. | ||
| 3. Create a changeset if needed. | ||
| 4. Run tests (`pnpm test`) and fix any failures. | ||
| 5. Push the branch and create a PR via `gh pr create`. |
There was a problem hiding this comment.
This assumes users have gh installed, however we don't require it in the project. Maybe we could fallback to the classic git command
|
To me the disclosure is useful to understand what I'm preparing for. It's not about code, but interaction. If I know I'm about to interact with prompts (there are users that reply to comments with AI), then I know I don't need to put energies and empathy in my messages |
5 participants
Changes
AGENTS.mdcovering branch naming, conventional commits, changesets, and the expected PR workflow..github/PULL_REQUEST_TEMPLATE.md).AI-generatedorAI-assistedin the PR description.Testing
No code changes — documentation only. Verified the markdown renders correctly and the relative link to the PR template resolves.
Docs
This is the docs change. No user-facing behavior affected.