diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index 7bfd3ae4..8d3f4771 100644 --- a/.specify/memory/constitution.md +++ b/.specify/memory/constitution.md @@ -1,11 +1,11 @@ # Generate Release Notes Action Constitution @@ -42,10 +42,16 @@ New placeholders, chapters, or hierarchy features MUST default to non-breaking b uncertain. Document additions in README + release notes. Rationale: Incremental evolution without destabilizing existing users. -### Principle 7: Resource-Conscious GitHub API Usage -All mining MUST route through rate limiter abstractions. Disable hierarchy expansion when feature off. Avoid redundant -fetches (cache IDs once retrieved). Performance concerns addressed before merging API-heavy features. -Rationale: Preserves rate limits & improves speed. +### Principle 7: Resource-Conscious GitHub API Usage & Performance Budgeting +All mining MUST route through rate limiter abstractions and remain within a documented soft performance budget. +Rules: +- Disable hierarchy expansion when feature off to avoid unnecessary calls. +- Avoid redundant fetches (cache IDs once retrieved). +- Verbose runs SHOULD (and CI MAY) log: total API requests, elapsed wall-clock seconds, issues processed, PRs processed, remaining rate limit. +- Soft API call target: ≤ 3 * (issues + PRs) for typical release windows; overages require justification & follow-up optimization task. +- If remaining core rate limit <10% before optional hierarchy expansion, skip hierarchy mining with a warning (do not fail build). +- Performance baselines MUST be periodically (at least once per quarter) captured for representative repositories. +Rationale: Preserves rate limits, ensures predictably fast runtime, and prevents hidden performance regressions. ### Principle 8: Lean Python Design Prefer pure functions; introduce classes ONLY when stateful behavior or polymorphism required. Avoid deep inheritance; @@ -64,7 +70,7 @@ Rationale: Prevents confusion & keeps coverage meaningful. ### Principle 11: Focused & Informative Comments Comments MUST succinctly explain non-obvious logic, constraints, or workaround rationale. Prohibited: stale, narrative, -Speculative, or redundant comments. Maintain or delete on change; never leave outdated intent. +speculative, or redundant comments. Maintain or delete on change; never leave outdated intent. Rationale: Enhances clarity without noise. ### Principle 12: Test Path Mirroring @@ -93,9 +99,48 @@ Rules: - Descriptor: lowercase kebab-case; hyphens only; no spaces/underscores/trailing slash. - Optional numeric ID may precede description: `fix/987-label-trim`. - Avoid vague terms (`update`, `changes`); state intent (`improve-logging`, `relabel-duplicate-detection`). -- Forbidden: mixing categories (e.g., `feature-fix/`), uppercase, camelCase. -- Scope alignment: PR description MUST align with chosen prefix category; reviewers reject mismatches (e.g., docs-only PR on feature/ branch). -Rationale: Enables automated classification, precise audit tooling, clearer commit/PR history semantics, and supports future CI policy enforcement. +- Forbidden: mixing categories, uppercase, camelCase. +- Scope alignment: PR description MUST align with chosen prefix category. +Rationale: Enables automated classification, clearer history semantics, and supports CI policy enforcement. + +### Principle 14: Static Typing Discipline +All production modules MUST be fully type-checked with `mypy` (no silent exclusion beyond legacy transitional areas explicitly documented). +Rules: +- New code MAY NOT introduce `# type: ignore` without inline justification. +- Broad `Any` disallowed unless interacting with third-party library lacking stubs (justify in PR). +- Progressive enforcement: expand mypy coverage to tests by 2025-11-01 (create issue if deadline adjustment needed). +Rationale: Early defect detection, self-documenting APIs, safer refactors. + +### Principle 15: TODO Debt Governance +Inline `TODO` (or `FIXME`) MUST include an issue reference (`#`). Format: `# TODO(|): `. +Rules: +- Missing issue link blocks merge (unless converted immediately to issue during review). +- TODO lifetime max: 2 MINOR releases; aged TODOs trigger escalation issue. +- Deprecated TODO replaced by comment removal OR fixed code in same PR. +Rationale: Prevents silent entropy & ensures planned remediation of technical debt. + +### Principle 16: Security & Token Handling +No secrets or token fragments MAY be logged (even at DEBUG). Environment access limited to documented inputs. +Rules: +- Mask potentially sensitive substrings when logging dynamic user inputs. +- Dependencies updated under `chore/` branches; review for supply chain risk (pin versions in requirements files). +- Introduce new external services ONLY with explicit README threat notes (data sent, retention, opt-in flag). +Rationale: Protects consumers using default GITHUB_TOKEN and mitigates leakage risk. + +### Principle 17: Documentation‑Derived Rule Synchronization +Normative statements (MUST/SHOULD/SHALL/REQUIRED) introduced or changed in project Markdown docs (e.g., `README.md`, +`CONTRIBUTING.md`, `DEVELOPER.md`, any `docs/**/*.md`) MUST be reconciled with this constitution & templates. +Rules: +- Every PR modifying *.md files that adds/changes normative language MUST include one of: + 1. “Aligns with existing Principle X” (explicit reference), OR + 2. A Constitution amendment (new/updated principle), OR + 3. Justification that wording is purely explanatory (no new rule) using phrase: `NON-NORMATIVE` in PR description. +- If conflict between doc text and a principle arises, the constitution prevails until amended; PR MUST either patch docs or amends principles in same PR. +- Introduced process steps (e.g., ��run script X before commit”) MUST appear in: (a) constitution governance or quality gates section, OR (b) tasks template if feature-scoped. +- A Doc Rule Scan Script (planned) parses changed Markdown lines for regex: `\b(MUST|SHOULD|SHALL|REQUIRED)\b` and fails CI unless reconciliation note present. +- Template Propagation: When new normative doc rule is adopted, update: plan-template Constitution Check, spec-template alignment bullets, tasks-template path/quality gates. +- Quarterly Audit: Run scan across repo; produce report listing normative statements without principle references; open issues for each orphan. +Rationale: Prevents silent drift between contributor docs and enforceable governance; ensures single source of truth & predictable automation. ## Quality & Testing @@ -103,49 +148,58 @@ Rationale: Enables automated classification, precise audit tooling, clearer comm - tests/unit/: All unit tests (test_.py) — required location. - tests/integration/: End-to-end tests (integration_test.py to be migrated here when reorganized). - tests/fixtures/: Optional static data samples. - - tests/helpers/ & tests/utils/: Test-only helpers (utils may merge into helpers). -- Framework: pytest ONLY (no unittest classes). -- Coverage: Enforce threshold ≥80% (existing command uses --cov-fail-under=80). New logic must keep or raise coverage. -- Independence: Tests MUST not depend on run order or mutate shared global state beyond fixture scope. + - tests/helpers/ & tests/utils/: Test-only helpers. +- Framework: pytest ONLY. +- Coverage: Enforce threshold ≥80% (uses --cov-fail-under=80). New logic must keep or raise coverage. +- Independence: Tests MUST not depend on execution order or mutate global state beyond fixture scope. - Parametrization: Use @pytest.mark.parametrize instead of manual loops. -- Integration tests import public interfaces only (e.g., main entry, generator class). +- Integration tests import public interfaces only. - Failing tests are written first (Principle 1) for new core logic. -- NEW: Path mirroring (Principle 12) enforced for all new/changed modules. -- Transitional Migration Plan: Add tasks in upcoming PRs to relocate remaining categorized tests. -- Branch Naming Check: Implementation PRs MUST originate from an allowed prefixed branch (`feature/`, `fix/`, `docs/`, `chore/`). (Principle 13) +- Path mirroring (Principle 12) enforced for all new/changed modules. +- Branch naming check enforced (Principle 13). +- Typing coverage gate (Principle 14). +- TODO audit gate (Principle 15). +- Performance summary logged in verbose mode (Principle 7) when enabled. +- Documentation rule sync: PR review checklist confirms Principle 17 compliance for any *.md normative additions. ## Workflow & Quality Gates -Pre-merge local mandatory checkers (from DEVELOPER.md): -1. Formatting: black --check (line length 120 per pyproject.toml). -2. Linting: pylint global score target ≥9.5 (no fatal errors). -3. Typing: mypy (0 blocking errors) — treat Any proliferation as smell (justify if unavoidable). +Pre-merge mandatory local (and CI) gates: +1. Formatting: black --check (line length 120). +2. Linting: pylint global score ≥9.5 (no fatal errors). +3. Typing: mypy (0 blocking errors); justify new ignores. 4. Tests: pytest all green. -5. Coverage: ≥80% overall; justify any temporary dip (must be recovered within next PR). -6. Dead Code: grep for unused utilities; remove or reference usage in same PR. -7. Determinism: (Manual) Validate repeated runs produce identical output for sample dataset. -8. Branch Naming: CI/Review MUST verify allowed prefix (feature|fix|docs|chore). Non-compliant branches BLOCK merge until renamed. +5. Coverage: ≥80% overall; justify any temporary dip. +6. Dead Code: remove or justify. +7. Determinism: repeat test run yields identical sample output. +8. Branch Naming: enforced allowed prefix. +9. TODO Governance: all TODOs issue-linked & within lifetime window. +10. Performance Budget (when verbose/perf job active): API call soft target evaluation (Principle 7). +11. Documentation Rule Sync: normative doc changes reconciled per Principle 17. Quality Gate Failure Handling: -- Minor failures (formatting, lint) → fix immediately; do not merge with waivers unless urgent hotfix. -- Coverage dip → requires explicit justification + recovery plan (link issue ID). -- Non-deterministic output → BLOCKING until resolved. -- Branch naming violation → BLOCKING until branch renamed; no exception (prefix set: feature|fix|docs|chore). +- Minor failures (formatting, lint) → immediate fix; no waivers unless urgent hotfix. +- Coverage dip → explicit justification + recovery issue. +- Non-deterministic output → BLOCKING. +- Branch naming violation → BLOCKING until renamed. +- TODO governance failure → BLOCKING (fix or link issue). +- Performance overrun → CONDITIONAL (document + follow-up optimization task) unless causing timeouts → BLOCKING. +- Documentation rule sync failure → BLOCKING until reconciliation (add amendment or clarify NON-NORMATIVE). ## Governance - Constitution supersedes ad-hoc practices; PRs MUST state compliance or list justified exceptions. - Versioning (this constitution): Semantic (MAJOR.MINOR.PATCH). - MAJOR: Remove/redefine a principle or backward incompatible process change. - - MINOR: Add new principle/section (current change qualifies here: Branch Naming Consistency). - - PATCH: Clarifications/typos with no semantic effect. + - MINOR: Add new principle/section or materially expand guidance. + - PATCH: Clarifications, numbering/order corrections, non-semantic wording. - Amendment Flow: 1. Propose change with rationale & impact assessment. 2. Update Sync Impact Report header (include affected templates & TODOs). 3. Bump version according to rule above. - 4. Obtain maintainer approval (≥1) — emergency fixes allow retroactive review. -- Compliance Review: PR template SHOULD reference Principles 1, 2, 10, 12, 13 (multi-prefix) + coverage threshold. Reviewers reject if principles violated without justification. + 4. Obtain ≥1 maintainer approval (emergency fixes allow post-hoc review). +- Compliance Review: PR template SHOULD reference Principles 1, 2, 7, 10, 12, 13, 14, 15, 17 + coverage threshold. - Backward Compatibility: Input names & placeholder semantics require MAJOR bump if changed. -- Enforcement: CI pipeline SHOULD automate black, pylint, mypy, pytest, coverage threshold; manual deterministic checks remain. Branch naming can be auto-validated by simple prefix check script. +- Enforcement: CI automates formatting, lint, typing, tests, coverage, branch prefix, TODO lint, and optional performance logging. -**Version**: 1.4.0 | **Ratified**: 2025-10-12 | **Last Amended**: 2025-10-14 +**Version**: 1.6.0 | **Ratified**: 2025-10-12 | **Last Amended**: 2025-10-15 diff --git a/.specify/templates/plan-template.md b/.specify/templates/plan-template.md index 3cb340d9..0fb1a376 100644 --- a/.specify/templates/plan-template.md +++ b/.specify/templates/plan-template.md @@ -30,15 +30,20 @@ *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* Mandatory alignment items: -- Test‑First Reliability: Provide failing unit test list BEFORE implementation. -- Explicit Configuration Boundaries: All new behavior exposed via action inputs (list any new inputs needed). -- Deterministic Output Formatting: Confirm ordering & placeholders remain stable. -- Lean Python Design: Justify each new class; prefer functions for stateless logic. -- Localized Error Handling: Define how errors are logged instead of cross-module exceptions. -- Dead Code Prohibition: Identify any code to delete made obsolete by this feature. -- Test Path Mirroring: Confirm new unit tests placed in `tests/unit//test_.py`. -- Branch Naming Consistency: Confirm current branch uses allowed prefix (feature|fix|docs|chore): +- Test‑First Reliability (P1): Provide failing unit test list BEFORE implementation. +- Explicit Configuration Boundaries (P2): All new behavior exposed via action inputs (list any new inputs needed). +- Deterministic Output Formatting (P3): Confirm ordering & placeholders remain stable. +- Performance Budget & API Usage (P7): Estimate added API calls (target ≤3*(issues+PRs)), define logging/measurement plan, and fallback behavior if rate limit low. +- Lean Python Design (P8): Justify each new class; prefer functions for stateless logic. +- Localized Error Handling (P9): Define how errors are logged instead of cross-module exceptions. +- Dead Code Prohibition (P10): Identify any code to delete made obsolete by this feature. +- Test Path Mirroring (P12): Confirm new unit tests placed in `tests/unit//test_.py`. +- Branch Naming Consistency (P13): Confirm current branch uses allowed prefix (feature|fix|docs|chore): `git rev-parse --abbrev-ref HEAD | grep -E '^(feature|fix|docs|chore)/'`. +- Static Typing Discipline (P14): Public APIs fully typed; list any unavoidable `Any` / `type: ignore` with justification. +- TODO Debt Governance (P15): Any introduced TODO lines MUST carry issue reference; list initial issues here. +- Security & Token Handling (P16): No logging of secrets; describe any new external API interactions & masking strategy. +- Documentation‑Derived Rule Sync (P17): Any new/changed normative doc statements reconciled (reference principle / amendment / NON-NORMATIVE justification). ## Project Structure diff --git a/.specify/templates/spec-template.md b/.specify/templates/spec-template.md index 218cfad9..ae0a627b 100644 --- a/.specify/templates/spec-template.md +++ b/.specify/templates/spec-template.md @@ -10,12 +10,17 @@ List how this feature will comply with core principles: - Test‑First (P1): Failing unit tests in `tests/unit/test_.py` BEFORE implementation. - Explicit Configuration Boundaries (P2): New behavior exposed only via documented action inputs (list if any needed). - Deterministic Output (P3): Define ordering / formatting impacts; MUST remain stable across runs. +- Performance Budget & API Usage (P7): Provide expected API call impact, measurement method (verbose logs / baseline script), and mitigation if nearing rate limit. - Lean Python Design (P8): Prefer functions; justify any new class (state or polymorphism requirement). - Localized Error Handling (P9): Describe logging + return strategy; no cross-module exception raises. - Dead Code Prohibition (P10): Identify any functions to remove or refactor; commit with tests. - Focused Comments (P11): Plan for concise logic/rationale comments; avoid narrative. - Test Path Mirroring (P12): Place unit tests at `tests/unit//test_.py`. - Branch Naming Consistency (P13): Branch MUST start with one of: `feature/`, `fix/`, `docs/`, `chore/`. Use kebab-case descriptor (optional numeric ID). Rename before merge if violated. +- Static Typing Discipline (P14): All new public functions fully typed; list any `Any` / `type: ignore` with justification. +- TODO Debt Governance (P15): Any new TODO includes issue link (format `TODO():`); enumerate added TODO items. +- Security & Token Handling (P16): Confirm no sensitive values logged; describe any new external service interactions + masking. +- Documentation‑Derived Rule Sync (P17): Normative *.md changes reference principle, create amendment, or are marked NON-NORMATIVE. ## User Scenarios & Testing *(mandatory)* diff --git a/.specify/templates/tasks-template.md b/.specify/templates/tasks-template.md index 1740d823..17b8f96e 100644 --- a/.specify/templates/tasks-template.md +++ b/.specify/templates/tasks-template.md @@ -21,13 +21,11 @@ description: "Task list template for feature implementation" - Tests MUST go under `tests/unit/` (unit) or `tests/integration/` (integration) - Mirrored paths: For `release_notes_generator/x/y.py` create `tests/unit/release_notes_generator/x/test_y.py`. - Branch naming: Branch MUST start with allowed prefix (feature|fix|docs|chore) + kebab-case descriptor. +- Typing: New or changed public functions MUST include full type annotations (Principle 14). +- TODOs: Any introduced TODO must include issue reference per `TODO():` pattern (Principle 15). +- Performance: If feature affects mining/data fetch loops, add measurement & API budget validation task (Principle 7). - + ## Phase 1: Setup (Shared Infrastructure) @@ -35,9 +33,11 @@ description: "Task list template for feature implementation" - [ ] T001 Create any new module directories in `release_notes_generator/` - [ ] T002 [P] Ensure mirrored test path structure for new/relocated tests (Principle 12) -- [ ] T002a Verify branch prefix matches regex `^(feature|fix|docs|chore)/` (Principle 13) or rename before proceeding -- [ ] T003 [P] Add initial failing unit tests in `tests/unit/` for new logic (Test‑First gate) -- [ ] T004 [P] Configure/verify linting and formatting tools +- [ ] T003 Verify branch prefix matches regex `^(feature|fix|docs|chore)/` (Principle 13) or rename before proceeding +- [ ] T004 [P] Add initial failing unit tests in `tests/unit/` for new logic (Test‑First gate) +- [ ] T005 [P] Configure/verify linting, typing (mypy) and formatting tools (Principles 1, 14) +- [ ] T006 [P] Add TODO pattern linter or script (Principle 15) +- [ ] T007 [P] Add performance baseline/measurement scaffold if feature impacts API calls (Principle 7) --- @@ -47,10 +47,11 @@ description: "Task list template for feature implementation" **⚠ CRITICAL**: No user story work can begin until this phase is complete -- [ ] T005 Implement feature configuration parsing (test: `tests/unit/test_action_inputs.py` extended) -- [ ] T006 [P] Add utilities (if needed) with tests (`tests/unit/test_utils_.py`) -- [ ] T007 Setup error handling pattern (log & return) — no cross-module exception leakage -- [ ] T008 Dead code removal (list obsolete functions) + tests ensuring replacement paths +- [ ] T008 Implement feature configuration parsing (test: `tests/unit/test_action_inputs.py` extended) +- [ ] T009 [P] Add utilities (if needed) with tests (`tests/unit/test_utils_.py`) +- [ ] T010 Setup error handling pattern (log & return) — no cross-module exception leakage +- [ ] T011 Dead code removal (list obsolete functions) + tests ensuring replacement paths +- [ ] T012 Security review: confirm no sensitive logging added (Principle 16) **Checkpoint**: Foundation ready - user story implementation can now begin in parallel @@ -64,14 +65,15 @@ description: "Task list template for feature implementation" ### Mandatory Tests for User Story 1 -- [ ] T009 [P] [US1] Unit tests for new pure functions in `tests/unit/test_.py` (start failing) -- [ ] T010 [US1] Update integration test (if scope touched) in `tests/integration/test_generation.py` (optional creation) +- [ ] T013 [P] [US1] Unit tests for new pure functions in `tests/unit/test_.py` (start failing) +- [ ] T014 [US1] Update integration test (if scope touched) in `tests/integration/test_generation.py` (optional creation) ### Implementation for User Story 1 -- [ ] T011 [P] [US1] Implement function(s) in `release_notes_generator/.py` -- [ ] T012 [US1] Logging additions (INFO lifecycle, DEBUG details) -- [ ] T013 [US1] Ensure deterministic ordering adjustments +- [ ] T015 [P] [US1] Implement function(s) in `release_notes_generator/.py` (full typing - P14) +- [ ] T016 [US1] Logging additions (INFO lifecycle, DEBUG details) without secrets (P5, P16) +- [ ] T017 [US1] Ensure deterministic ordering adjustments (P3) +- [ ] T018 [US1] Capture performance metrics (API calls & elapsed) if applicable (P7) **Checkpoint**: User Story 1 fully functional & independently testable @@ -85,12 +87,13 @@ description: "Task list template for feature implementation" ### Mandatory Tests for User Story 2 -- [ ] T014 [P] [US2] Unit tests for added logic +- [ ] T019 [P] [US2] Unit tests for added logic ### Implementation for User Story 2 -- [ ] T015 [US2] Implement logic in existing module -- [ ] T016 [US2] Update records builder ensuring no cross-module exceptions +- [ ] T020 [US2] Implement logic in existing module (maintain typing - P14) +- [ ] T021 [US2] Update records builder ensuring no cross-module exceptions (P9) +- [ ] T022 [US2] Update/extend performance measurement if scope affects API usage (P7) **Checkpoint**: User Stories 1 & 2 independently functional @@ -104,12 +107,14 @@ description: "Task list template for feature implementation" ### Mandatory Tests for User Story 3 -- [ ] T017 [P] [US3] Unit tests for added logic +- [ ] T023 [P] [US3] Unit tests for added logic ### Implementation for User Story 3 -- [ ] T018 [US3] Implement functionality -- [ ] T019 [US3] Update documentation/comments (concise, logic-focused) +- [ ] T024 [US3] Implement functionality +- [ ] T025 [US3] Update documentation/comments (concise, logic-focused) (P11) +- [ ] T026 [US3] Add/adjust TODOs with issue references (P15) +- [ ] T027 [US3] Re-run performance snapshot if affected (P7) **Checkpoint**: All user stories functional; tests green @@ -119,9 +124,10 @@ description: "Task list template for feature implementation" - [ ] TXXX [P] Documentation updates in `README.md`, `docs/` - [ ] TXXX Code cleanup (remove any newly unused code) -- [ ] TXXX Performance optimization +- [ ] TXXX Performance optimization / confirm within budget (P7) - [ ] TXXX [P] Additional unit tests (edge cases) in `tests/unit/` -- [ ] TXXX Security/robustness improvements +- [ ] TXXX Security/robustness improvements (P16) +- [ ] TXXX TODO sweep: ensure all TODOs have current issue links and none expired (P15) --- @@ -148,8 +154,12 @@ Add each story with its own failing tests → implementation → validation cycl ## Notes -- Avoid unused functions (delete immediately if obsoleted) -- Prefer functions over classes unless state/polymorphism required -- Handle errors locally; log & return -- Comments concise & logic-focused -- Test Path Mirroring required for new tests +- Avoid unused functions (delete immediately if obsoleted) (P10) +- Prefer functions over classes unless state/polymorphism required (P8) +- Handle errors locally; log & return (P9) +- Comments concise & logic-focused (P11) +- Test Path Mirroring required for new tests (P12) +- Enforce full typing & minimal ignores (P14) +- TODOs require issue linkage (P15) +- No sensitive output in logs (P16) +- Monitor API calls & elapsed runtime (P7)