Model version and change control: preserve what each result meant

Start with the actual first edition

The Investment Model Library first edition is dated 2026-10-16, with reference cards identified as version 1.0.0. That is the starting identity, not evidence of earlier public releases, a migration history or years of use. A change-control guide can explain what later revisions would require without inventing such revisions. Keep publication date, calculation version, source revision and input fixture identity distinct. A corrected sentence in an article may change a documentation revision without changing a formula. A change in the formula's denominator, by contrast, can alter the meaning of every numerical output even when its field name remains unchanged.

Define the public mathematical contract

Semantic Versioning requires a declared public interface before major, minor and patch labels can communicate compatibility. For a mathematical reference, that interface includes input units, defaults, admissible domains, output units, error behavior and numerical conventions. Treating only function names as the interface misses changes that matter most to a reader. For example, returning annual volatility where the contract promised per-period volatility is incompatible even if both values are ordinary numbers. Define compatibility against documented behavior, not against whether a demonstration page still loads. This makes version decisions reviewable instead of leaving them to a vague assessment of how large the code change looks.

Classify proposed changes by effect

A backward-compatible correction of an implementation defect can qualify as a patch, while compatible added functionality can qualify as a minor change and an incompatible public-contract change requires a major version. Those labels do not measure economic importance. Correcting a sign bug may dramatically change results while restoring the already documented formula. The table contains hypothetical proposals only. An optional diagnostic is compatible only if the output contract permits it and existing results retain their meaning. Changing a default covariance denominator is different: unless the existing promise already required the replacement denominator, callers receive a different estimator without changing their requests.

Show numerical impact with a fixed fixture

Use unchanged inputs to explain a behavior change. For the synthetic observations 0.01, 0.02, 0.03 and 0.04, the mean is 0.025 and the sum of squared deviations is 0.0005. Dividing by four gives population variance 0.000125; dividing by three gives sample variance approximately 0.0001666667. The latter is one third larger. Both calculations can be mathematically correct, but substituting one for the other changes the estimator. An impact note should identify the old and proposed conventions, affected outputs and unaffected cases. A diff that shows only edited lines cannot substitute for that numerical explanation.

Bind releases to inspectable artifacts

A readable version label should resolve to exact source and artifact identities. Git's documentation distinguishes lightweight tags from annotated tags, which carry additional metadata and can be signed. Neither a memorable tag name nor a version string alone demonstrates that a particular distributed file matches its source. Retain the resolved revision and the distributed file's digest with the release evidence. If a label is accidentally moved, the recorded identities allow the mismatch to be detected. Avoid treating a mutable branch name as a complete reproduction reference. It describes a line of development, not necessarily the calculation a reader previously inspected.

Review dependencies and documentation together

A dependency update can change numerical results or error handling without an obvious edit to the model's own source. Recheck fixtures, boundary cases and output serialization before deciding that behavior is unchanged. Compare the card's prose, formula and executable example together so the documentation does not describe one estimator while the implementation calculates another. Record intentional rounding changes separately from full-precision result changes. A change request should contain a reason, compatibility assessment, relevant tests and limitations. These are proposed review practices for reference material, not a statement that any unattended release process or external approval system is operating.

Correct without rewriting the record

When a published calculation is found to be wrong, preserve its identity and explain the correction rather than silently replacing its evidence. Mark affected examples clearly, identify a corrected version when one actually exists, and retain enough context to understand earlier exports. Restoring an older bundle can recover an earlier behavior, but it does not make that behavior correct or restore compatibility with newer input contracts. A useful correction notice distinguishes formula errors, fixture errors and presentation errors because their consequences differ. Versioning earns its value by keeping those distinctions inspectable, not by making every change sound like an improvement.

Primary references

These sources support methods and conventions. The example values are original constructions, not observations extracted from these documents.

• Semantic Versioning 2.0.0: public interface and compatibility rules
• Pro Git: lightweight and annotated tags

Related investigations