From 8d40dc5ab796b4ccc22c728e1475c06ca14eccbd Mon Sep 17 00:00:00 2001 From: Fredrik Bakke Date: Wed, 14 May 2025 11:18:20 +0100 Subject: [PATCH 1/5] self review guidelines --- SELF-REVIEW-GUIDELINES.md | 87 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 SELF-REVIEW-GUIDELINES.md diff --git a/SELF-REVIEW-GUIDELINES.md b/SELF-REVIEW-GUIDELINES.md new file mode 100644 index 0000000000..c6773660e0 --- /dev/null +++ b/SELF-REVIEW-GUIDELINES.md @@ -0,0 +1,87 @@ +# Self-review and merge guidelines + +## Purpose + +This document outlines the process for maintainers to perform self-reviews and +merge pull requests without a second maintainer review. The goal is to maintain +high-quality contributions while enabling progress when maintainers have limited +availability. + +## When self-review is appropriate + +Self-review and merge is appropriate for maintainers under the following +conditions: + +- The PR has been open for at least 3 weeks +- No maintainer has had time to review the PR +- The changes follow established practices and don't introduce novel library + approaches + +**Note:** Self-review is only appropriate for maintainers. PRs from regular +contributors should still undergo review by at least one maintainer. + +## Required waiting period + +1. Submit your PR and request reviews from other maintainers +2. Wait for at least 3 weeks from the last substantive change to the PR +3. If no review has been provided after sending reminders, proceed with + self-review + +This waiting period serves two purposes: + +- It provides a grace period for others to review and give input +- It allows you to look at your code with fresh eyes before performing the + self-review + +## Self-review checklist + +Before merging your own PR, make sure to review each of the following aspects: + +### Mathematical correctness + +- [ ] Mathematical statements are correct +- [ ] Terminology is consistent with established literature +- [ ] For concepts not appearing in literature, disclaimers have been added +- [ ] Claims without accompanying formalization include appropriate citations + +### Documentation + +- [ ] All new terms are clearly defined +- [ ] Documentation is clear and accessible +- [ ] Citations are provided when introducing new terminology +- [ ] You can confidently say: "I will understand this paragraph in a year" + +### Content quality + +- [ ] Content follows the library's conventions as outlined in + - [Design principles](DESIGN-PRINCIPLES.md) + - [Coding style](CODINGSTYLE.md) + - [File conventions](FILE-CONVENTIONS.md) + - [Guidelines for mixfix operators](MIXFIX-OPERATORS.md) + - [Citing sources](CITING-SOURCES.md) +- [ ] No duplication with existing content + +## Seeking assistance + +If you have questions during the self-review process: + +1. For quick questions, ask in the project Discord or message the other + maintainers +2. For more complex issues, consider creating an issue on GitHub +3. Don't wait indefinitely for responses; use your best judgment if responses + are not forthcoming +4. Document significant decisions in your PR description + +## Final merge requirements + +Before merging your PR: + +1. Complete and document the self-review process in the PR +2. State that you're merging under the self-review policy after the 3-week + waiting period +3. Be prepared to address any issues discovered after merging + +## Continuous improvement + +Remember that the ultimate goal is to maintain high-quality contributions while +enabling the project to progress despite limited reviewer availability. From afa392a5af4454842e626e58ccf60f82652879ad Mon Sep 17 00:00:00 2001 From: Fredrik Bakke Date: Wed, 14 May 2025 11:22:45 +0100 Subject: [PATCH 2/5] edits --- SELF-REVIEW-GUIDELINES.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/SELF-REVIEW-GUIDELINES.md b/SELF-REVIEW-GUIDELINES.md index c6773660e0..04d95a5db1 100644 --- a/SELF-REVIEW-GUIDELINES.md +++ b/SELF-REVIEW-GUIDELINES.md @@ -3,9 +3,9 @@ ## Purpose This document outlines the process for maintainers to perform self-reviews and -merge pull requests without a second maintainer review. The goal is to maintain -high-quality contributions while enabling progress when maintainers have limited -availability. +merge pull requests without a second maintainer's review. The goal is to +maintain high-quality contributions while enabling progress when maintainers +have limited availability. ## When self-review is appropriate @@ -43,6 +43,7 @@ Before merging your own PR, make sure to review each of the following aspects: - [ ] Terminology is consistent with established literature - [ ] For concepts not appearing in literature, disclaimers have been added - [ ] Claims without accompanying formalization include appropriate citations +- [ ] Changes to existing content are uncontroversial and well-justified ### Documentation From 8b427fc5338262d4689b6bcb39622c7b74dbc54f Mon Sep 17 00:00:00 2001 From: Fredrik Bakke Date: Wed, 14 May 2025 11:24:07 +0100 Subject: [PATCH 3/5] reword --- SELF-REVIEW-GUIDELINES.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/SELF-REVIEW-GUIDELINES.md b/SELF-REVIEW-GUIDELINES.md index 04d95a5db1..a06c1fe3c7 100644 --- a/SELF-REVIEW-GUIDELINES.md +++ b/SELF-REVIEW-GUIDELINES.md @@ -14,8 +14,8 @@ conditions: - The PR has been open for at least 3 weeks - No maintainer has had time to review the PR -- The changes follow established practices and don't introduce novel library - approaches +- The changes follow established practices and don't introduce novel approaches + to the library's organization **Note:** Self-review is only appropriate for maintainers. PRs from regular contributors should still undergo review by at least one maintainer. From e1a170b990d6d94f9a725e8ec23090c7705a0c42 Mon Sep 17 00:00:00 2001 From: Fredrik Bakke Date: Wed, 14 May 2025 11:27:11 +0100 Subject: [PATCH 4/5] edits --- SELF-REVIEW-GUIDELINES.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/SELF-REVIEW-GUIDELINES.md b/SELF-REVIEW-GUIDELINES.md index a06c1fe3c7..90ccb527fb 100644 --- a/SELF-REVIEW-GUIDELINES.md +++ b/SELF-REVIEW-GUIDELINES.md @@ -66,9 +66,11 @@ Before merging your own PR, make sure to review each of the following aspects: If you have questions during the self-review process: -1. For quick questions, ask in the project Discord or message the other - maintainers -2. For more complex issues, consider creating an issue on GitHub +1. For quick questions, ask in the + [project Discord](https://discord.gg/Zp2e8hYsuX) or message the other + [maintainers](MAINTAINERS.md) +2. For more complex issues, consider creating an + [issue on GitHub](https://github.com/UniMath/agda-unimath/issues) 3. Don't wait indefinitely for responses; use your best judgment if responses are not forthcoming 4. Document significant decisions in your PR description From cd29438c36e2d1fb56f2136a1d909b4c6cc4e5d1 Mon Sep 17 00:00:00 2001 From: Fredrik Bakke Date: Wed, 14 May 2025 11:33:07 +0100 Subject: [PATCH 5/5] reword --- SELF-REVIEW-GUIDELINES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SELF-REVIEW-GUIDELINES.md b/SELF-REVIEW-GUIDELINES.md index 90ccb527fb..971c16a727 100644 --- a/SELF-REVIEW-GUIDELINES.md +++ b/SELF-REVIEW-GUIDELINES.md @@ -60,7 +60,7 @@ Before merging your own PR, make sure to review each of the following aspects: - [File conventions](FILE-CONVENTIONS.md) - [Guidelines for mixfix operators](MIXFIX-OPERATORS.md) - [Citing sources](CITING-SOURCES.md) -- [ ] No duplication with existing content +- [ ] There is no duplication with existing content ## Seeking assistance