Migrations/bookorbit
1
0
Fork 0
mirror of https://github.com/bookorbit/bookorbit.git synced 2026-11-03 00:11:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs: update PR template and contributing guide review requirements

Browse Source
This commit is contained in:
neon
2026-08-01 18:22:56 +00:00
parent 02debbe543
commit 9262704f0a
2 changed files with 71 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/pull_request_template.md
+60 -37
View File
@@ -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?
<!--
A short summary of the change and why it's needed.
Link at least one issue using a GitHub closing keyword, for example:
- Closes #123
- Fixes: #123
- RESOLVED owner/repo#123
-->
> [!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`)
<!-- Tell us what you actually did to verify this works. What did you run? What did you click through?
A quick note like "spun up Docker, added a book, confirmed it shows in the library" is perfect.
This helps us review with confidence and speeds up the merge. -->
## What changed
## Screenshots
<!-- What changed, why it is needed, and what a user sees differently. Two or three sentences. -->
<!-- If this touches the UI, please include a before/after screenshot or a short screen recording.
You can drag and drop images directly here. -->
## Verification
## Anything non-obvious in the diff?
**Commands run.** Paste the real output tail, including the summary lines. Do not reconstruct or
summarize it.
<!-- Did you make any tricky decisions or trade-offs? Anything you'd want a reviewer to pay
extra attention to? This is your chance to guide the review. -->
```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.
<!-- Drag files in here, or write "No UI changes." -->
## 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
<!-- Write "None" for each field if no AI tool was involved. -->
<details open>
<summary><b>Contributor checklist</b></summary>
- [ ] 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)
</details>
docs/CONTRIBUTING.md
+11 -10
View File
@@ -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