Skip to content

docs: add meaningful change threshold guide (#148) - #155

Merged
El-swaggerito merged 1 commit into
Axionvera:mainfrom
angelraph:feat/meaningful-change-threshold-guide
Jul 29, 2026
Merged

docs: add meaningful change threshold guide (#148)#155
El-swaggerito merged 1 commit into
Axionvera:mainfrom
angelraph:feat/meaningful-change-threshold-guide

Conversation

@angelraph

Copy link
Copy Markdown
Contributor

Description

Adds a dedicated "Meaningful Change Threshold" guide for Aegis Contracts PRs, per #148. Some PRs have landed with very small diffs that don't solve the underlying issue; this guide makes explicit that line count is not the standard — completeness against the issue's acceptance criteria is — and gives contributors and reviewers a concrete way to judge it.

New doc: docs/meaningful-change-threshold.md, which:

  • States the core principle (line count is not the standard) with a "three questions" test for whether a change clears the threshold.
  • Gives paired ~2-line Rust examples of a small-but-complete fix vs. a small-but-incomplete one that looks similar but leaves the reported vulnerability unfixed.
  • Lists concrete patterns of insufficient changes (cosmetic-only, partial fixes, tests without a fix, suppressing warnings instead of fixing, silently narrowed scope, doc-only responses to behavioural bugs).
  • Gives reviewer assessment guidance: read the issue's acceptance criteria first, ask "does reverting just this diff bring the bug back?", check tests actually fail pre-change, watch for TODO/#[allow] stand-ins, confirm partial scope is disclosed — and apply the same standard regardless of diff size.

It is scoped to avoid duplicating docs/meaningful-implementation-checklist.md (the technical completeness bar — auth/events/errors/tests) — the two docs now cross-link to clarify the division of labor. Also linked from README.md and added to the Related Documents list in docs/contributor-evaluation-policy.md.

Related Issues

Closes #148

Completion Table

Acceptance Criterion Status Implementation Evidence Test Evidence
AC 1: Meaningful change threshold guide is added Complete docs/meaningful-change-threshold.md (new file) N/A (docs-only)
AC 2: Guide explains that line count alone is not the only measure Complete "Why this exists" and "The threshold: three questions" sections N/A (docs-only)
AC 3: Small but complete changes are distinguished from small but incomplete changes Complete "Small but complete vs. small but incomplete" section, paired worked examples N/A (docs-only)
AC 4: Insufficient examples are included Complete "Examples of insufficient changes" section (6 concrete patterns) N/A (docs-only)
AC 5: Reviewer assessment guidance is included Complete "Reviewer assessment guidance" section N/A (docs-only)
AC 6: README links to the guide Complete README.md — new bullet in ## CI & Contributing N/A (docs-only)

No criteria are partial or deferred.

Detailed Traceability Mapping

Not applicable — this PR makes no storage, event, or security-control changes (documentation only).

Type of Change

  • Documentation update

PR Evidence Checklist

1. Issue Reference

2. Implementation Summary

  • Summary provided above.
  • Files modified:
    • docs/meaningful-change-threshold.md (new) — the guide itself.
    • README.md — links the guide from ## CI & Contributing.
    • docs/meaningful-implementation-checklist.md — adds a cross-reference to the new guide.
    • docs/contributor-evaluation-policy.md — adds the new guide to ## Related Documents.
  • No new public functions, events, error codes, or roles introduced (docs-only change).

3. Tests Added or Justification

  • No-test justification: this is a documentation-only change with no src/ logic, so there is no behaviour for src/test.rs to cover. make test is unaffected and passes as before (no contract code touched).

4. Commands Run

  • make verify not applicable to a docs-only diff (no Rust source changed); confirmed no src/, tests/, Cargo.toml, or Makefile files are touched by git diff --stat.

5. CI Status

  • No Rust/build/test CI surface is affected by this change.

6. Acceptance Criteria Coverage

Policy & Standards

  • I have read the Contributor Evaluation Policy and understand that merge does not guarantee payment.
  • I have read the CONTRIBUTING.md guidelines.
  • N/A — no Rust code changed (fmt/clippy/test not applicable to a docs-only PR).
  • Traceability Mapping: Completion Table above covers all criteria; no storage/event/security changes to map in detail.
  • Reviewer Guidance: reviewed the diff against the Reviewer Checklist's documentation/quality criteria.
  • Compliance & Legal Check: this guide is a process/documentation guide and makes no claims about regulatory completeness.

Additional Context

This directly responds to the issue's stated concern about very small merged PRs that don't resolve the underlying issue. The new guide is deliberately narrow in scope (judging scope/completeness) so it complements rather than duplicates the existing meaningful-implementation-checklist.md (technical bar) and aegis-contracts-examples.md (failure-category gallery).

Adds docs/meaningful-change-threshold.md explaining that line count
alone is not the standard for judging PR completeness, with
small-but-complete vs small-but-incomplete examples, insufficient-change
patterns, and reviewer scope-assessment guidance. Cross-links it from
README.md, the Meaningful Implementation Checklist, and the Contributor
Evaluation Policy so it doesn't duplicate their existing content.

Closes #148
@El-swaggerito
El-swaggerito merged commit 18ee36f into Axionvera:main Jul 29, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add Aegis Contracts meaningful change threshold guide

2 participants