docs: require flat branch names for docs-only PRs

Docs preview URLs (coder.com/docs/@branch-name) break when the branch name contains a / because the Next.js router cannot disambiguate branch segments from doc path segments. There is no fix on the website side (coder/coder.com#379 was rejected). Add agent guidance to use flat branch names for docs-only PRs and include a preview base URL in the PR description.
2026-04-10 11:50:46 +00:00
1 changed files with 9 additions and 0 deletions
@@ -184,6 +184,15 @@ git pull origin branch-name

 Don't use `git push --force` unless explicitly requested.

+### Docs-only PRs
+
+For PRs that change **only** `docs/` files, use a flat branch name
+without `/` (e.g., `docs-fix-gateway-setup`, not
+`user/docs-fix-gateway-setup`). The docs preview site serves branch
+previews at `https://coder.com/docs/@<branch-name>` and `/` in the
+branch name breaks this URL. Include the preview base URL in the PR
+description so reviewers can browse the rendered changes.
+
 ### New Feature Checklist

 - [ ] Run `git pull` to ensure latest code