From 10a3880d42c9d4440459dd04348b4ec3878b0e2f Mon Sep 17 00:00:00 2001 From: OpenCode Date: Wed, 8 Jul 2026 12:28:35 +0700 Subject: [PATCH] Add 10 issue management and PR review docs Closes #601, Closes #602, Closes #603, Closes #604, Closes #605, Closes #606, Closes #607, Closes #608, Closes #609, Closes #610 --- docs/evidence/CHANGE_NOTE_GUIDE.md | 26 ++++++++++++++++++++++ docs/evidence/DUPLICATE_ISSUE_GUIDE.md | 15 +++++++++++++ docs/evidence/ISSUE_BATCHING_GUIDE.md | 22 ++++++++++++++++++ docs/evidence/ISSUE_CLOSING_POLICY.md | 22 ++++++++++++++++++ docs/evidence/ISSUE_DECOMPOSITION_GUIDE.md | 24 ++++++++++++++++++++ docs/evidence/ISSUE_DEPENDENCY_GUIDE.md | 16 +++++++++++++ docs/evidence/ISSUE_LABEL_GUIDE.md | 16 +++++++++++++ docs/evidence/ISSUE_PRIORITY_RUBRIC.md | 10 +++++++++ docs/evidence/MILESTONE_PLANNING_GUIDE.md | 20 +++++++++++++++++ docs/evidence/PR_REVIEW_RUBRIC.md | 23 +++++++++++++++++++ tests/test_batch_10_v3.py | 26 ++++++++++++++++++++++ 11 files changed, 220 insertions(+) create mode 100644 docs/evidence/CHANGE_NOTE_GUIDE.md create mode 100644 docs/evidence/DUPLICATE_ISSUE_GUIDE.md create mode 100644 docs/evidence/ISSUE_BATCHING_GUIDE.md create mode 100644 docs/evidence/ISSUE_CLOSING_POLICY.md create mode 100644 docs/evidence/ISSUE_DECOMPOSITION_GUIDE.md create mode 100644 docs/evidence/ISSUE_DEPENDENCY_GUIDE.md create mode 100644 docs/evidence/ISSUE_LABEL_GUIDE.md create mode 100644 docs/evidence/ISSUE_PRIORITY_RUBRIC.md create mode 100644 docs/evidence/MILESTONE_PLANNING_GUIDE.md create mode 100644 docs/evidence/PR_REVIEW_RUBRIC.md create mode 100644 tests/test_batch_10_v3.py diff --git a/docs/evidence/CHANGE_NOTE_GUIDE.md b/docs/evidence/CHANGE_NOTE_GUIDE.md new file mode 100644 index 00000000..ffc4d5f7 --- /dev/null +++ b/docs/evidence/CHANGE_NOTE_GUIDE.md @@ -0,0 +1,26 @@ +# Change Note Writing Guide + +How to write good change notes for PRs and releases. + +## Structure + +Each change note should follow this format: + +``` +- ``path/to/changed/file`` — Brief description of what changed and why. +``` + +## Examples + +``` +- ``src/openamp_foundry/pipeline.py`` — Added charge_bias score to candidate output. +- ``docs/evidence/LIMITATIONS_OVERVIEW.md`` — Added calibration limitations section. +``` + +## Rules + +- Start with the file path in backticks. +- Use past tense for what was done. +- Include the reason if it's not obvious. +- Keep each entry to one line when possible. +- Group related changes together. diff --git a/docs/evidence/DUPLICATE_ISSUE_GUIDE.md b/docs/evidence/DUPLICATE_ISSUE_GUIDE.md new file mode 100644 index 00000000..6e15be14 --- /dev/null +++ b/docs/evidence/DUPLICATE_ISSUE_GUIDE.md @@ -0,0 +1,15 @@ +# Duplicate Issue Handling Guide + +How to identify and handle duplicate issues. + +## Steps + +1. Before creating a new issue, search for existing issues with similar keywords. +2. If a duplicate is found, comment on the new issue linking to the original. +3. Close the duplicate with a note referencing the original issue number. +4. If the duplicate contains unique information, add it as a comment to the original issue before closing. + +## Prevention + +- Maintain a clear issue label system (see ISSUE_LABEL_GUIDE.md). +- Review open issues regularly for potential duplicates. diff --git a/docs/evidence/ISSUE_BATCHING_GUIDE.md b/docs/evidence/ISSUE_BATCHING_GUIDE.md new file mode 100644 index 00000000..84aa98cc --- /dev/null +++ b/docs/evidence/ISSUE_BATCHING_GUIDE.md @@ -0,0 +1,22 @@ +# Issue Batching Guide + +How to batch related issues into efficient PRs. + +## When to Batch + +- Issues are in the same area of the codebase. +- Issues are small and independent. +- Issues have the same reviewer. + +## When NOT to Batch + +- Issues touch safety policy — keep separate. +- Issues have different priorities. +- Issues require different review expertise. + +## Best Practices + +- Limit batches to 10 issues per PR. +- List all closed issues in the PR description. +- Use "Closes #N, Closes #M" format. +- Ensure each issue has its own commit or clear scope in squashed commit. diff --git a/docs/evidence/ISSUE_CLOSING_POLICY.md b/docs/evidence/ISSUE_CLOSING_POLICY.md new file mode 100644 index 00000000..040657a2 --- /dev/null +++ b/docs/evidence/ISSUE_CLOSING_POLICY.md @@ -0,0 +1,22 @@ +# Issue Closing Policy + +When to close issues and how. + +## Valid Closing Reasons + +- The change has been implemented and merged. +- The issue is a duplicate of another issue. +- The issue is out of scope for the project. +- The issue cannot be reproduced. +- The issue has been deferred and is tracked in a milestone. + +## Required Information + +- The closing comment should explain why the issue is being closed. +- If the issue was resolved by a PR, link the PR. +- If the issue was deferred, link the tracking milestone or epic. + +## Not Valid Reasons + +- "We don't have time for this" — assign to a milestone instead. +- "This is too hard" — break into smaller issues. diff --git a/docs/evidence/ISSUE_DECOMPOSITION_GUIDE.md b/docs/evidence/ISSUE_DECOMPOSITION_GUIDE.md new file mode 100644 index 00000000..3c420732 --- /dev/null +++ b/docs/evidence/ISSUE_DECOMPOSITION_GUIDE.md @@ -0,0 +1,24 @@ +# Issue Decomposition Guide + +How to break large issues into manageable pieces. + +## When to Decompose + +- An issue is estimated to take more than one sprint. +- An issue touches multiple independent areas. +- An issue cannot be reviewed as a single PR. + +## Decomposition Strategy + +1. Identify the independent sub-tasks. +2. Create separate issues for each sub-task. +3. Link the sub-tasks to the parent epic. +4. Order the sub-tasks by dependency. +5. Assign each sub-task to a milestone. + +## Example + +Instead of one issue "Improve documentation," create: +- "Fix broken links in docs/" +- "Add concept cards for evidence types" +- "Update QUICKSTART.md for new CLI flags" diff --git a/docs/evidence/ISSUE_DEPENDENCY_GUIDE.md b/docs/evidence/ISSUE_DEPENDENCY_GUIDE.md new file mode 100644 index 00000000..a0ab3187 --- /dev/null +++ b/docs/evidence/ISSUE_DEPENDENCY_GUIDE.md @@ -0,0 +1,16 @@ +# Issue Dependency Guide + +How to track and manage dependencies between issues. + +## Identifying Dependencies + +- Issue A depends on Issue B if A cannot be started until B is complete. +- Use the "depends on" feature in GitHub Issues. +- Document the dependency in both issues' descriptions. + +## Managing Dependencies + +- Order dependent issues in the same milestone. +- If a dependency blocks a milestone, escalate it. +- If a dependency is itself blocked, consider breaking it into smaller issues. +- Remove the dependency if the issues can be worked on independently. diff --git a/docs/evidence/ISSUE_LABEL_GUIDE.md b/docs/evidence/ISSUE_LABEL_GUIDE.md new file mode 100644 index 00000000..1c995a0c --- /dev/null +++ b/docs/evidence/ISSUE_LABEL_GUIDE.md @@ -0,0 +1,16 @@ +# Issue Label Guide + +Standard labels used in the OpenAMP Foundry repo. + +| Label | Meaning | +|-------|---------| +| `good-first-issue` | Suitable for new contributors | +| `help-wanted` | Needs contributor attention | +| `bug` | Something is broken | +| `enhancement` | New feature or improvement | +| `docs` | Documentation change | +| `safety` | Safety-related change | +| `benchmark` | Benchmark-related change | +| `calibration` | Calibration pipeline change | +| `release` | Release preparation | +| `urgent` | Needs immediate attention | diff --git a/docs/evidence/ISSUE_PRIORITY_RUBRIC.md b/docs/evidence/ISSUE_PRIORITY_RUBRIC.md new file mode 100644 index 00000000..520e19c1 --- /dev/null +++ b/docs/evidence/ISSUE_PRIORITY_RUBRIC.md @@ -0,0 +1,10 @@ +# Issue Priority Rubric + +How to assign priority to issues. + +| Priority | Label | Response Time | Example | +|----------|-------|:-------------:|---------| +| P0 | critical | < 24h | Safety policy error, broken CLI | +| P1 | high | < 72h | Benchmark regression, broken test | +| P2 | medium | < 1 week | Missing feature, doc gap | +| P3 | low | Best effort | Nice-to-have improvement | diff --git a/docs/evidence/MILESTONE_PLANNING_GUIDE.md b/docs/evidence/MILESTONE_PLANNING_GUIDE.md new file mode 100644 index 00000000..122a95ee --- /dev/null +++ b/docs/evidence/MILESTONE_PLANNING_GUIDE.md @@ -0,0 +1,20 @@ +# Milestone Planning Guide + +How to plan and manage milestones. + +## Milestone Structure + +| Milestone | Duration | Focus | +|-----------|:--------:|-------| +| v0.6.x | 2 weeks | Bug fixes, small improvements | +| v0.7.x | 4 weeks | Feature work | +| v0.8.x | 4 weeks | Integration, testing | +| v1.0 | TBD | Release candidate | + +## Planning Process + +1. Review open issues and group by area. +2. Estimate effort (small/medium/large). +3. Select issues for the milestone based on priority and capacity. +4. Assign issues to the milestone in GitHub. +5. Review progress at milestone midpoint. diff --git a/docs/evidence/PR_REVIEW_RUBRIC.md b/docs/evidence/PR_REVIEW_RUBRIC.md new file mode 100644 index 00000000..60071144 --- /dev/null +++ b/docs/evidence/PR_REVIEW_RUBRIC.md @@ -0,0 +1,23 @@ +# PR Review Rubric by Risk Class + +How to review PRs based on their risk level. + +| Risk Class | Examples | Review Required | Review Depth | +|------------|----------|:---------------:|:------------:| +| Low | Typo fixes, formatting, docs | 1 maintainer | Surface-level | +| Medium | New tests, minor features | 1 maintainer | Functional review | +| High | Policy changes, safety, calibration | 2 maintainers | Deep review | +| Critical | Release, security, safety policy | 3 maintainers + project lead | Full audit | + +## Low-Risk Review Checklist + +- [ ] Tests pass +- [ ] No overclaiming language +- [ ] No broken links + +## High-Risk Review Checklist (all of the above plus) + +- [ ] Design doc or RFC exists +- [ ] Safety implications reviewed +- [ ] Backward compatibility considered +- [ ] Rollback plan documented diff --git a/tests/test_batch_10_v3.py b/tests/test_batch_10_v3.py new file mode 100644 index 00000000..8958554d --- /dev/null +++ b/tests/test_batch_10_v3.py @@ -0,0 +1,26 @@ +"""Tests for batch of 10 docs.""" +from pathlib import Path + +FILES = [ + "ISSUE_PRIORITY_RUBRIC.md", + "ISSUE_LABEL_GUIDE.md", + "MILESTONE_PLANNING_GUIDE.md", + "ISSUE_BATCHING_GUIDE.md", + "ISSUE_CLOSING_POLICY.md", + "DUPLICATE_ISSUE_GUIDE.md", + "ISSUE_DEPENDENCY_GUIDE.md", + "ISSUE_DECOMPOSITION_GUIDE.md", + "PR_REVIEW_RUBRIC.md", + "CHANGE_NOTE_GUIDE.md", +] + + +def test_all_exist(): + for f in FILES: + assert Path("docs/evidence", f).exists(), f"Missing: {f}" + + +def test_each_has_content(): + for f in FILES: + text = Path("docs/evidence", f).read_text() + assert len(text) > 50, f"{f} too short"