Repository navigation
Record the behaviour changes since 1.4.0, and link the docs that exist - #741
Merged
Merged
Conversation
AGENTS.md says a published API that returns the wrong answer is a bug with users rather than an asset -- "say so in the changelog, and change it". There was nowhere to say it: CHANGELOG.md is one line pointing at the site, and 61 commits of behaviour changes have landed since v1.4.0 with the reasoning living only in commit messages nobody hits when their build breaks. BREAKING-CHANGES.md is that record. Every entry gives the value on 1.4.0 and the value now, measured on a build of each rather than read off the diff, with the issue and the PR. Entries are marked silent where the call still succeeds and quietly returns something else, which are the ones that cost a reader time: `exp(x)` was the product `exp * x` and is now `e^x`, `Real`'s `-7 % 3` was -1 and is 2, `sqrt(12)` is now reduced wherever a radical is built, `Simplify` of a cancelling quotient returns a Providedf where it returned a Divf, and `x^5 + 3x + 1` came back with 28 roots and comes back with 5. Measuring both sides rather than trusting the commit messages changed four entries. `arccos(-1/2)` prints `2/3 * pi`, `sec(t)^2 - tan(t)^2` comes back `1 provided not cos(t) = 0` rather than 1, and the free parameter a under-determined system answers with arrives unsimplified. More substantially, `int x(x^2+x+1)^2` and `int x^2(x^2+1)^2` were correct antiderivatives on 1.4.0 and are unevaluated today -- they reached an answer through the by-parts re-entry that overflowed the stack on `int x*ln(x)`, so bounding that closed their route too. That is a loss and is written down as one. Two stale claims in AGENTS.md turned up while linking the docs it never pointed at. `Sources/Tests/UnitTests/Common/IssueRegressionTest.cs` does not exist; the regressions live in SimplificationRegressionTest, SolverRegressionTest and NumericsRegressionTest, with AlreadyFixedIssuesTest for the separate case of an open issue that already works. And Docs/Contributing/RS1617Errors.md tells you to add public members to a PublicApi.*.txt, when neither those files nor the analyzer that wanted them are in the tree any more; the new section says not to follow it. Docs only -- no code changed, so no suite was run.
Rafael-SOWNet
changed the title
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.
AGENTS.md says a published API that returns the wrong answer is a bug with users rather than an asset — "say so in the changelog, and change it". There was nowhere to say it.
CHANGELOG.mdis one line pointing at the site, and 61 commits of behaviour changes have landed sincev1.4.0with the reasoning living only in commit messages, which is not where anyone looks when their build breaks.BREAKING-CHANGES.mdis that record.What is in it
Every entry gives the value on 1.4.0 and the value now, measured on a build of each rather than read off the diff, with the issue and the PR it came from. Entries are marked silent where the call still succeeds and quietly returns something else, since those are the ones that cost a reader an afternoon:
exp(x)exp * xe ^ xlog10(100)log ^ 10 * 1002(Real)(-7) % 3-12sqrt(12)sqrt(12)2 * sqrt(3), wherever a radical is builtSimplifyof a cancelling quotientDivfProvidedf(x - x = 0).Solve(x){ 0 }CCx^5 + 3x + 1lim x->0 (1+x)^(1/x)1eMinusf.Minuendona - bbaOrganised by surface — types, parsing, printing, numbers, remainder, simplification, solving, limits, calculus, compilation — so a reader arrives with a symptom and leaves with the reason.
Measuring both sides was worth it
Four entries changed once measured against a
v1.4.0build instead of trusting the commit messages:arccos(-1/2)prints2/3 * pi,sec(t)^2 - tan(t)^2comes back1 provided not cos(t) = 0rather than1, and the free parameter an under-determined system answers with arrives unsimplified.The substantial one:
int x(x^2+x+1)^2andint x^2(x^2+1)^2were correct antiderivatives on 1.4.0 and are unevaluated today. Differentiating each back on a 1.4.0 build gives the integrand exactly at every point tried. They reached an answer through the integration-by-parts re-entry that overflowed the stack onint x*ln(x), so bounding that closed their route as well. That is a loss, not a fix, and it is written down as one rather than filed under improvements.Two stale claims found while linking the docs
AGENTS.md linked almost nothing, so this also adds a Where things are written down section. Wiring it up surfaced two things that were not true:
Sources/Tests/UnitTests/Common/IssueRegressionTest.cs, which AGENTS.md named as the home for issue regressions, does not exist. They live inSimplificationRegressionTest,SolverRegressionTestandNumericsRegressionTest, withAlreadyFixedIssuesTestfor the separate case of an open issue that already works.Docs/Contributing/RS1617Errors.mdtells you to add public members to aPublicApi.*.txt. Neither those files nor the analyzer that required them are in the tree any more. The new section says not to follow it and suggests deleting or rewriting it — happy to do that here if you would rather it went now.Measured
Both columns come from console harnesses built against
v1.4.0and against40ce1093, run side by side. Every relative link in the four changed files resolves to a real path, checked by script.Docs only — no code changed, so no suite was run.
🤖 Generated with Claude Code