From 9262704f0a8ae3f1db6bcf31003708874adfb469 Mon Sep 17 00:00:00 2001 From: neon <18559658+neonsolstice@users.noreply.github.com> Date: Sat, 1 Aug 2026 18:22:56 +0000 Subject: [PATCH] docs: update PR template and contributing guide review requirements --- .github/pull_request_template.md | 97 ++++++++++++++++++++------------ docs/CONTRIBUTING.md | 21 +++---- 2 files changed, 71 insertions(+), 47 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index d7e9aa929..39e0b161b 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,47 +1,70 @@ -## Before you submit - -> **New feature?** Please open an issue first and get approval from the maintainers before writing any code. -> PRs that introduce features without a prior discussion will be closed. -> -> **Used AI assistance?** That's fine - but make sure you've read and understood every line of the diff -> before submitting. PRs that show no sign of self-review will be closed without detailed feedback. -> -> **Keep it focused.** One thing per PR. Don't bundle a bug fix with a refactor or unrelated cleanup. -> If it's not ready, open it as a draft instead. - ---- - -## What does this PR do? - - +> [!IMPORTANT] +> Ready-for-review PRs must satisfy every applicable section below. Incomplete submissions are closed +> without detailed review, and you are welcome to resubmit once complete. Open a draft PR if the work +> is not finished. Closes # -## How did you test this? +- **Type:** bug fix | feature | refactor | docs | chore +- **UI changed:** yes | no +- **How I ran this:** `pnpm dev` | Docker | I did not run it +- **Evidence captured at commit:** (run `git rev-parse --short HEAD`) - +## What changed -## Screenshots + - +## Verification -## Anything non-obvious in the diff? +**Commands run.** Paste the real output tail, including the summary lines. Do not reconstruct or +summarize it. - +```text -## Checklist +``` -- [ ] I've read through my own diff -- [ ] This PR was discussed in an issue and has maintainer approval (for new features) -- [ ] Lint and tests pass locally -- [ ] No unintended files included (build artifacts, `.env`, personal configs) +**Manual testing.** Answer in your own words and be specific. "Tests pass" is not manual testing. + +1. **First thing you did once it was running, and what you saw:** + +2. **What went wrong or surprised you along the way:** + +3. **What this change is most likely to break, and how you checked that specifically:** + +**Anything you could not test:** + +## Evidence + +UI changes require screenshots. Changes to behavior or interaction also require a short recording of +the complete workflow. Screenshots must show the surrounding browser window rather than a cropped +element, and recordings must start from a page load. For backend changes, paste the log lines your +change emits. + + + +## Authorship and review + +AI assistance is welcome on this project; unreviewed AI output is not. See the +[AI usage policy](https://github.com/bookorbit/bookorbit/blob/main/docs/AI_POLICY.md). + +- **AI tools used:** +- **Extent (what they wrote, and what you wrote):** +- **How you verified their output yourself:** +- [ ] I can explain any line of this diff on request + + + +
+Contributor checklist + +- [ ] One focused change, linked above to an issue a maintainer approved +- [ ] I read every line of the final diff +- [ ] `pnpm verify` passes against the final diff +- [ ] Tests added or updated per the [testing expectations](https://github.com/bookorbit/bookorbit/blob/main/docs/CONTRIBUTING.md#phase-7-write-and-run-tests) +- [ ] User-facing text is localized and accessibility was checked, where applicable +- [ ] Documentation updated, where applicable +- [ ] No unintended files, secrets, build artifacts, or personal configuration included +- [ ] No new dependencies, or the addition was discussed and approved in the linked issue +- [ ] I followed the [contribution guidelines](https://github.com/bookorbit/bookorbit/blob/main/docs/CONTRIBUTING.md) and [commit guidelines](https://github.com/bookorbit/bookorbit/blob/main/docs/COMMIT_GUIDELINES.md) + +
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 3f51c3393..5385ee4f9 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -113,13 +113,13 @@ Refer to [DEVELOPMENT.md](DEVELOPMENT.md) for architecture details, project stru Testing expectations depend on what you changed: -| Change type | What is expected | -| ----------------------- | ----------------------------------------------- | -| Bug fix | Regression test proving the bug is fixed | -| New backend feature/API | Server unit tests for the new behavior | -| New frontend logic | Client unit tests (composables, utilities) | -| UI-only change | Manual verification evidence (screenshot/video) | -| Refactor | Existing tests stay green, no new tests needed | +| Change type | What is expected | +| ----------------------- | ---------------------------------------------- | +| Bug fix | Regression test proving the bug is fixed | +| New backend feature/API | Server unit tests for the new behavior | +| New frontend logic | Client unit tests (composables, utilities) | +| UI-only change | Screenshots, plus a recording for interactions | +| Refactor | Existing tests stay green, no new tests needed | Run the full test suite: @@ -170,13 +170,13 @@ git push origin BO-123-your-feature-name When creating the PR: -- **Fill out the PR template.** It asks for a summary, testing evidence, screenshots (if UI changed), and non-obvious decisions. +- **Fill out the PR template.** It asks for a summary, the commands you ran with their real output, what you did while manually testing, visual evidence for UI changes, and an authorship note covering any AI assistance. - **Use a Conventional Commit-style PR title** (for example: `fix(reader): correct page count for multi-volume PDFs`). - **Link your issue** with a GitHub closing keyword in the description (`close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved`) and an issue reference (`#123` or `owner/repo#123`). Example: ```md - ## What does this PR do? + ## What changed Correct page count handling for multi-volume PDFs. @@ -184,6 +184,7 @@ When creating the PR: ``` - **Open as a draft** if you want early direction feedback before the code is complete. +- **Attach visual evidence for UI changes.** Include screenshots for every UI change and a short screen recording when behavior or interaction changes. Ready-for-review PRs missing applicable visual evidence will be closed without review and may be resubmitted once complete. - **Disclose AI usage** if applicable. See [AI_POLICY.md](AI_POLICY.md) for the format and expectations. ### Phase 11: Respond to Review @@ -216,7 +217,7 @@ Before marking your PR ready for review, confirm: - [ ] `pnpm verify` passes locally - [ ] Tests included per the [testing expectations table](#phase-7-write-and-run-tests) - [ ] Full-stack behavior manually validated -- [ ] UI changes include screenshot or recording +- [ ] UI changes include screenshots, plus a recording when behavior or interaction changed - [ ] PR template fully completed - [ ] No unintended files (build artifacts, `.env`, personal configs) - [ ] No unapproved new dependencies