Define what is and is not covered by SemVer

[oxinabox]

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]

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

[StefanKarpinski]

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]

@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]

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]

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.