Skip to content

Pull Request Revert Policy

Purpose

Reverts protect users, safeguard maintainability, and preserve scientific integrity when a merged change causes regressions that cannot wait for a fix-forward. They are not punitive—they provide a fast, low-risk way to restore a reliable baseline so contributors can investigate and reintroduce the change safely.

When to Revert

Trigger a revert only for serious issues in parts of the code that are not marked as "beta":

Typical revert triggers

  • Major correctness bugs (e.g., broken conservation, highly unstable solver, incorrect physics equations).
  • Significant performance regressions on maintained benchmarks (typically >10–15% slower without an acceptable trade-off).
  • Broken builds or CI on supported targets (CPU, CUDA, HIP) that cannot be repaired quickly. This applies even for beta features.
  • Incompatible output-format changes that break existing plotfile readers.
  • Unreproducible outputs or race conditions exposed by deterministic reruns or sanitizer tooling.
  • Security or licensing concerns (e.g., unsafe dependency, incompatible license).

Revert Workflow

  1. Open an issue summarising impact, affected versions, and how to reproduce. Label it regression, revert-candidate, and add backport-needed if release branches are affected.
  2. Prepare the revert PR:
  3. Title it Revert: #<original-PR> <original title>.
  4. Use git revert <merge-commit-sha> when possible to keep history clean.
  5. Keep the change minimal—no refactors or unrelated fixes.
  6. Add a failing test that reproduces the problem (fails on development, passes after the revert).
  7. Explain clearly in the PR body: user impact, scope, why revert beats a quick fix-forward, and the plan to reintroduce safely if needed.
  8. Review & merge quickly—aim for ≤3 business days once consensus forms. One maintainer approval is enough for low-risk internal fixes; require two approvals when the original change was high risk or broadly user-facing.

After the Revert

Post-merge checklist

  • File a follow-up issue to fix forward: root cause, new tests, ADR if architecture changes are involved.
  • Note the revert in the changelog and backport to supported release branches if users rely on the affected feature.
  • For ParmParse or problem-file interface changes, publish a migration guide before attempting re-introduction.

Guiding Principles

Guiding principles

  • Prefer a temporary revert plus a clear follow-up plan over leaving the code broken.
  • Always attach evidence (inputs, logs, benchmarks) to justify the revert.
  • Keep the revert PR surgical and traceable to the original change.
  • Treat reverts as a collaborative safety measure; focus on the fix, not assigning blame.