From ddf285f5684cf6489878901925c9a28d8e37463f Mon Sep 17 00:00:00 2001 From: neon <18559658+neonsolstice@users.noreply.github.com> Date: Fri, 7 Aug 2026 19:07:25 +0000 Subject: [PATCH] docs: require approval and end-to-end evidence --- .github/ISSUE_TEMPLATE/bug_report.yml | 15 +++++++++ .github/ISSUE_TEMPLATE/feature_request.yml | 15 +++++++++ .github/pull_request_template.md | 39 ++++++++++++++++++---- docs/CONTRIBUTING.md | 31 ++++++++++++----- 4 files changed, 85 insertions(+), 15 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 1b7015fd2..34655c06a 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -55,6 +55,19 @@ body: label: Screenshots (optional) description: Drag and drop screenshots here if applicable. + - type: markdown + attributes: + value: | + ### Before implementing a fix + + If you want to implement a fix, comment on the issue with your proposed approach after submitting + it. Wait for a maintainer to approve the approach and assign the issue to you before writing code + or opening a pull request, including a draft. + + If nobody responds within seven days, leave one polite follow-up and @mention the maintainers or + contributors already involved in the issue. People may have missed the original notification, so + a reminder is welcome. No response does not count as approval. + - type: checkboxes id: checklist attributes: @@ -62,3 +75,5 @@ body: options: - label: I've searched existing issues and this hasn't been reported yet. required: true + - label: If I implement this fix, I will wait for maintainer approval and assignment before writing code or opening a pull request. + required: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 961022cc5..f54432a55 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -36,6 +36,19 @@ body: validations: required: true + - type: markdown + attributes: + value: | + ### Before implementing this request + + If you want to implement this request, comment on the issue with your proposed approach after + submitting it. Wait for a maintainer to approve the approach and assign the issue to you before + writing code or opening a pull request, including a draft. + + If nobody responds within seven days, leave one polite follow-up and @mention the maintainers + or contributors already involved in the issue. People may have missed the original notification, + so a reminder is welcome. No response does not count as approval. + - type: checkboxes id: checklist attributes: @@ -43,3 +56,5 @@ body: options: - label: I've searched existing issues and this hasn't been requested yet. required: true + - label: If I implement this, I will wait for maintainer approval and assignment before writing code or opening a pull request. + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 003186d14..1b9db532c 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,10 +1,13 @@ > [!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 +> Before writing code or opening a PR, including a draft, discuss your approach in the linked issue +> and wait for a maintainer to approve it and assign the issue to you. PRs opened without prior +> approval and assignment will be closed without review. After approval, open a draft PR if the work > is not finished. Closes # +- **Maintainer approval:** (link to the approval comment) +- **Assigned contributor:** @ - **Type:** bug fix | feature | refactor | docs | chore - **UI changed:** yes | no - **How I ran this:** `pnpm dev` | Docker | I did not run it @@ -35,12 +38,33 @@ summarize it. ## 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. +Upload a recording that proves the changed behavior works in the real client. Show the starting state, +the user action, and the final result. If the workflow crosses multiple clients, show the result in +each affected client. - +Ready-for-review PRs without the required evidence will not be reviewed. Keep the PR in draft until +the evidence has been uploaded. + +Examples: + +- **Web:** Start from a page load, perform the affected workflow, and show the saved result after + refreshing the page. +- **KOReader:** Perform the affected workflow inside KOReader and show the result there. For sync + changes, also show the corresponding result in BookOrbit. +- **Kobo:** Perform the affected workflow on the device, run the sync, and show the resulting state on + the device and in BookOrbit where applicable. +- **Scanner, import, or metadata:** Add or modify a real book, run the operation through its normal + BookOrbit control, and show the resulting book state in the BookOrbit UI. +- **Server code used by a client:** Trigger the behavior from that client and show the result in the + client. Calling the endpoint directly is not end-to-end evidence. + +"No UI changes," written testing claims, automated test output, logs, API requests, database queries, +and direct service calls are not evidence. They may support the recording but cannot replace it. + +Evidence must match the final commit. If the workflow cannot be demonstrated in its real client or +device, keep the PR in draft and state what remains untested. + + ## Authorship and review @@ -58,6 +82,7 @@ AI assistance is welcome on this project; unreviewed AI output is not. See the Contributor checklist - [ ] One focused change, linked above to an issue a maintainer approved +- [ ] I discussed my approach and was assigned the issue before writing code or opening this PR - [ ] 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) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index c711809b4..9014d618f 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -44,7 +44,8 @@ This is the end-to-end journey from idea to merged PR. Each phase builds on the ### Phase 1: Find or Create an Issue -> **Issue first, PR second.** Every pull request must link to an approved issue. PRs without one will be closed. +> **Issue first, PR second.** Every pull request must link to an approved issue assigned to the +> contributor. PRs without prior approval and assignment will be closed without review. - Browse [open issues](../../issues) for something you want to tackle. - If you have a new idea, open one using the [bug report](../../issues/new?template=bug_report.yml) or [feature request](../../issues/new?template=feature_request.yml) template. @@ -52,12 +53,22 @@ This is the end-to-end journey from idea to merged PR. Each phase builds on the ### Phase 2: Get Maintainer Approval -Wait for explicit approval before writing code. Approval looks like: +Before writing code, comment on the issue to say that you want to implement it and briefly describe +your proposed approach. Then wait for both: -- A :+1: reaction on your issue. -- A comment such as "go ahead", "approved", or "approved to proceed". +- A maintainer comment explicitly approving the implementation. +- A maintainer assigning the issue to you. -This step prevents wasted effort on changes that conflict with the project direction. Small bug fixes with clear reproduction are usually approved quickly. +Do not start implementation or open a pull request, including a draft, until both have happened. A +reaction or lack of a response does not count as approval. + +If nobody responds within seven days, leave one polite follow-up comment and @mention the maintainers +or contributors already involved in the issue. People have responsibilities outside the project and +may simply have missed the original notification, so a reminder is welcome. Continue waiting for an +explicit reply before starting implementation or opening a pull request. + +This step prevents wasted effort on changes that conflict with the project direction. Small bug fixes +with clear reproduction are usually approved quickly. ### Phase 3: Fork and Clone @@ -183,7 +194,9 @@ git push origin BO-123-your-feature-name When creating the PR: -- **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. +- **Fill out the PR template.** It asks for the linked approval, a summary, the commands you ran with + their real output, what you did while manually testing, end-to-end evidence, 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: @@ -196,8 +209,10 @@ When creating the PR: Fixes: #123 ``` -- **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. +- **Open as a draft** if the implementation is incomplete after the linked issue has been approved and + assigned. Use the issue for direction before approval. +- **Attach end-to-end evidence.** Upload a recording showing the changed behavior through the real + client. Ready-for-review PRs without the required evidence will not be reviewed. - **Disclose AI usage** if applicable. See [AI_POLICY.md](AI_POLICY.md) for the format and expectations. ### Phase 11: Respond to Review