Define what is and is not covered by SemVer for Julia itself (Base Julia and stdlibs) #33684

oxinabox · 2019-10-26T11:51:37Z

We really should document this.
I figured I would start and people who know more could push directly to my branch.

TensorFlow has a good one of these pages in its docs

We could almost take these directly:

Floating point numerical details: The specific floating point values computed by ops may change at any time. Users should rely only on approximate accuracy and numerical stability, not on the specific bits computed. Changes to numerical formulas in minor and patch releases should result in comparable or improved accuracy, with the caveat that in machine learning improved accuracy of specific formulas may result in decreased accuracy for the overall system.

Random numbers: The specific random numbers computed by the random ops may change at any time. Users should rely only on approximately correct distributions and statistical strength, not the specific bits computed. However, we will make changes to random bits rarely (or perhaps never) for patch releases. We will, of course, document all such changes.

Bugs: We reserve the right to make backwards incompatible behavior (though not API) changes if the current implementation is clearly broken, that is, if it contradicts the documentation or if a well-known and well-defined intended behavior is not properly implemented due to a bug. For example, if an optimizer claims to implement a well-known optimization algorithm but does not match that algorithm due to a bug, then we will fix the optimizer. Our fix may break code relying on the wrong behavior for convergence. We will note such changes in the release notes.

Error behavior: We may replace errors with non-error behavior. For instance, we may change a function to compute a result instead or raising an error, even if that error is documented. We also reserve the right to change the text of error messages. In addition, the type of an error may change unless the exception type for a specific error condition is specified in the documentation

Keno · 2019-10-26T17:45:57Z

Pre 1.0 @StefanKarpinski had a Google doc somewhere that tracked this kind of thing.

StefanKarpinski · 2019-10-27T16:06:03Z

Here's the doc: https://docs.google.com/document/d/1WdlfucPHcesbNZXQ-eFx39evNkdseMe08GAPf8zEasY/edit?usp=sharing. If anyone wants to be able to edit, Slack me and I can give edit permissions. I haven't looked at this in a while, so not sure how much I still agree with what's in there. These are just the notes I took in the lead up to 1.0.

oxinabox · 2019-10-27T17:29:48Z

@StefanKarpinski do you want to attempt to transpose the bits of that that are still relevent into this PR,
and we can then work to clean the text up in git (rather than in google docs) ?

StefanKarpinski · 2019-10-28T13:42:35Z

I don't really have time at the moment, but yes, someone should probably filter through that and figure out what's relevant and put it in the docs along with what you've proposed.

laborg · 2020-05-10T08:15:00Z

FWIW: I'd be in favor to state that if a package A exposes dependency B via its API (e.g. a return type), then any major change in B regarding the exposed parts should require a major change in A.

DilumAluthge · 2026-02-09T03:06:04Z

This PR has had no activity for five years+, so I'll close it as stale.

@oxinabox If you're still interested in working on this PR, let me know, and I can re-open it.

oxinabox · 2026-02-09T03:07:38Z

We actually should still do this.
But idk if this PR is the place

Make a version of https://docs.sciml.ai/ColPrac/stable/#Changes-that-are-not-considered-breaking
which is official for julia itself.

DilumAluthge · 2026-02-09T03:39:40Z

I think there are a couple open questions:

Should we add a docs page like this? If yes, where should it go (Julia manual vs ~~Pkg.jl manual~~ vs somewhere else?)?
What should the contents of the docs page be?

I'll add the triage label, so that triage can discuss this. At this point, my question for triage is just the first part, specifically I'd like triage to answer the following:

Should we add a docs page like this? If yes, where should it go?

I think the second part (what should the contents be) is going to be tougher for triage to answer, although of course any feedback from triage is appreciated.

oxinabox · 2026-02-09T06:23:35Z

Note this is about what is covered by semver for julia itself.
Not advise to package authors.
But rather a promise (or disclaimer of promise) about what future versions of julia will do.

So it definately doesn't belong in the Pkg docs.
Except perhaps has a note to package authors that they might like to stick to similar standards as julia itself does.

oscardssmith · 2026-02-12T18:41:06Z