## Summary
Documents the policy around AI-assisted contributions, for both humans
and agents:
- `.github/pull_request_template.md`: notes that AI use is encouraged
for researching, creating, and reviewing changes, but contributors must
deeply understand their contributions, and PR descriptions from external
contributors must be written by a human.
- `.github/ISSUE_TEMPLATE/1.bug_report.yml`: adds the equivalent note
for bug reports — issue descriptions from external contributors must be
written by a human, though AI may help create reproductions.
- `AGENTS.md`: replaces the old "PR Descriptions" section with two new
sections. "GitHub Pull Requests" distinguishes branch PRs (agents may
write descriptions) from fork PRs targeting `vercel/next.js` (agents may
not). "GitHub Issues, Comments, and Discussions" restricts agent-written
issues, discussions, and comments to members of the
`vercel`/`vercel-labs` GitHub orgs, tells agents how to check membership
via the GitHub API, lists what agents can still help non-members with
(drafting details, reviewing, reproductions, translation, searching for
duplicates), and carves out exceptions (commenting on the user's own PR,
Vercel-operated bots, GitHub/Graphite review bots, and forks of the
repo).
- Renames the LLM watermark marker from `NEXT_JS_LLM_PR` to
`NEXT_JS_LLM` everywhere it appears (`AGENTS.md`,
`contributing/repository/pull-request-descriptions.md`, and the
`create-pr`/`backport-pr` skills), since it now also applies to issues,
discussions, and comments. Nothing in the repo consumes the old marker
name.
- `.agents/skills/create-pr/SKILL.md`: adds a "Fork PRs vs Branch PRs"
section referencing the `AGENTS.md` policy. Assorted typo fixes along
the way.
## Verification
- `gh api /user/memberships/orgs` and `gh api
orgs/vercel/members/<login>` (confirmed the documented membership checks
work and return the documented statuses)
- Not run: no test/build commands (docs-only change; prettier applied
via the pre-commit hook)
<!-- NEXT_JS_LLM -->
## What?
Adds contributor-facing guidance for the new signed-commit requirement.
- adds a `Signed commits` section to `contributing.md`
- adds a short signed-commit note to the PR template
- clarifies that a `Signed-off-by` line is not enough
## Why?
As signed commits become required, contributors need a clear explanation
in the repo and at PR time so they know what will be enforced and how to
recover from unsigned commits.
## How?
Documents the requirement in the main contribution guide and repeats the
key action items in the PR checklist.
## Testing
- docs-only change
- verified with local readback and diff review
<!-- NEXT_JS_LLM_PR -->
## For Maintainers
### What?
Removed the references to the now-deleted examples guidelines from the
PR template. Specifically, removed the line about
```
The "examples guidelines" are followed from our contributing doc https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md
```
since that file and folder were deleted in PR
[#77050](https://github.com/vercel/next.js/pull/77050).
### Why?
The `/examples` folder and its `adding-examples.md` file were removed,
so the reference in the PR template to those guidelines is outdated and
misleading. Keeping those references causes confusion for contributors
by pointing to non-existent documentation.
### How?
- Edited the PR template file.
- Removed the outdated examples guidelines reference line.
- Left other template content unchanged to preserve existing guidance.
This ensures the PR template stays accurate, up-to-date, and helpful for
contributors.
---------
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
Update our git workflow in preparation for open-sourcing the content of
the docs ([linear
task](https://linear.app/vercel/issue/DX-1579/set-up-github-workflow)).
**Templates:**
- [x] Update docs issue template to encourage contributions
- [x] Update PR template to include link to new contribution guide
**Code Owners / Reviewers:**
- https://github.com/vercel/next.js/pull/50841
**Labels:**
- [x] Add DevEx team to labeler.json so PRs get the "created by: DevEx
team"
**Other:**
- [x] Remove docs manifest from CI checks as we no longer have one (keep
the manifest for errors as they live under `/pages`)
- [x] Add `unifiedjs.vscode-mdx` to the vscode extension list
## What?
This PR has its main goal to improve the experience of opening/reviewing
a PR.
It improves the PR template, as well as extends PR auto-labeling.
## Why?
There are 2 parts to the PR template:
- Individual contributors: The current template accommodates for the
most common cases individual contributors use to contribute. (I.e.
fixing bugs, updating/adding examples, addressing documentation issues).
The new template keeps this at the top.
- Next.js team: As maintainers, we should try to explain PRs as if
someone with less context would review them. This should also help with
backreferencing PRs in issues and follow-up PRs and make it easier to
follow changes, understand trade-offs better at the time, and help new
team members catch up over time, etc.
## How?
The template is written in a comment instead of Markdown, so when the PR
is opened, most of the template is hidden to make it less verbose.
The checkboxes we've had before are not shown, but we already auto-label
PRs based on the path of the files that have been touched, so the
checkboxes showed redundant information.
[Slack
thread](https://vercel.slack.com/archives/C04DUD7EB1B/p1677677802109289),
Closes NEXT-741
Running "pnpm lint" on a documentation change won't work unless "pnpm
build" has previously been run, e.g. on a fresh checkout of a fork after
clicking the published docs "edit this on GitHub" button.
## Documentation / Examples
- [x] Make sure the linting passes by running `pnpm lint`
- [x] The "examples guidelines" are followed from [our contributing
doc](https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md)
Co-authored-by: JJ Kasper <jj@jjsweb.site>
Co-authored-by: Steven <steven@ceriously.com>
Continues #39778Closes#40499
## Bug
- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [ ] Errors have helpful link attached, see `contributing.md`
## Feature
- [ ] Implements an existing feature request or RFC. Make sure the
feature request has been accepted for implementation before opening a
PR.
- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [ ] Documentation added
- [ ] Telemetry added. In case of a feature if it's used or not.
- [ ] Errors have helpful link attached, see `contributing.md`
## Documentation / Examples
- [ ] Make sure the linting passes by running `pnpm lint`
- [ ] The examples guidelines are followed from [our contributing
doc](https://github.com/vercel/next.js/blob/canary/contributing.md#adding-examples)
Co-authored-by: Tim Neutkens <tim@timneutkens.nl>
Co-authored-by: JJ Kasper <jj@jjsweb.site>
Benjamin Woodruff