docs: add a numerical stability policy#23
Closed
yipjunkai wants to merge 1 commit into
Closed
Conversation
Closes the audit's "what version bump does an output-changing fix get?" question. #19 (deep-OTM pricing) and #21 (nan -> exceptions) both shipped output/behaviour changes as patch releases with no stated policy; this writes the contract down. New docs/numerical-stability.md states: - The guarantee is correctness to a documented tolerance (~1e-13 relative on well-posed inputs, ~1 ULP into the deep-OTM tail, 1e-8 vs py_vollib in the compat shim), NOT bit-for-bit reproducibility across versions. - Versioning: a pure accuracy refinement (same inputs, a more-correct number) ships as a disclosed fix:/perf: patch; a change to documented behaviour (return value, exception, signature, unit) is breaking -> minor pre-1.0. - Disclosure without a bespoke changelog section: the commit subject states the output change (release-please copies it into CHANGELOG.md verbatim) and the body quantifies it; goldens move in the same commit and the differential must still agree. Wires the policy into existing touchpoints: SECURITY.md's previously dangling "published numerical tolerance" now links here, CONTRIBUTING.md gains a PR-checklist item + a numerical-expectations bullet, and the README's Numerical agreement section points here. No release-please-config.json change: output changes use the existing Bug Fixes / Performance sections, not a custom "Numerical changes" section. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Owner
Author
|
Closing unmerged — maintainer decided the numerical-stability policy doc isn't needed at this stage. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
docs/numerical-stability.md— a short contract for how pyvolr versions and discloses changes to its numerical outputs — and wires it into the existing touchpoints. Implements the "Patch + disclose" stance.Closes the audit's #1 open question: #19 (deep-OTM pricing) and #21 (
nan→ exceptions) both shipped output/behaviour changes as patch releases with no written policy.The policy in one paragraph
The guarantee is correctness to a documented tolerance, not bit-for-bit reproducibility across versions (~1e-13 relative on well-posed inputs, ~1 ULP into the deep-OTM tail,
1e-8vspy_vollibin the compat shim). A pure accuracy refinement (same inputs, a more-correct number) ships as a disclosedfix:/perf:patch; a behaviour/contract change (return value, exception, signature, unit) is breaking → minor pre-1.0. Disclosure rides the existingBug Fixes/Performancechangelog sections: the commit subject states the change (release-please copies it verbatim), the body quantifies it, and goldens + the differential move with it.Files
docs/numerical-stability.mdSECURITY.mdCONTRIBUTING.mdREADME.mdDeliberately not done
No
release-please-config.jsonchange — output changes use the existing changelog sections, not a custom "Numerical changes" section (per maintainer preference; keeps release-please close to defaults).This PR is docs-only, so
ci.yml(whichpaths-ignores**.md/docs/**) does not run, and the sole required checkci-passedwill never report — the knownpaths-ignore+ required-ci-passedgap the audit scoped out. It will need an admin merge (as otherdocs:changes have). Verified locally instead: all 14 relative markdown links across the changed files resolve (0 broken). Shout if you'd rather I close the gap (a smallci.ymlskip-shim) or fold this into the item-3 PR (which touches a workflow and would trigger CI).🤖 Generated with Claude Code