[erlang-questions] On OTP rand module difference between OTP 19 and OTP 20

[Loïc Hoguin]

On 08/31/2017 04:20 PM, Jesper Louis Andersen wrote:
> On Thu, Aug 31, 2017 at 3:42 PM Loïc Hoguin <essen@REDACTED 
> <mailto:essen@REDACTED>> wrote:
> 
> 
>     I certainly hope this is not the general policy for OTP. We program
>     against the documentation. The documentation *is* our reality.
> 
> 
> I think it is fair to evaluate on a case by case basis.

I'm not arguing against that, but rather against that it's "in general 
safer to change the documentation".

It should be a case by case basis but it's also important to recognize 
that users write software against the documentation, and to take this 
into account when making breaking changes.

To give an example, if such a thing were to happen in Cowboy, which 
follows semver, two cases could happen:

* The documentation is wrong but the next version is a patch release: 
fix the code to match the documentation. The rule is: don't break 
people's programs.

* The documentation is wrong but the next version is a major release: 
fix the documentation AND announce it as a breaking change (with all 
details; and probably release a patch release for the old version as 
above). The rule is: breaking people's programs is OK, just make sure 
you tell them about it!

> I don't think you can make blanket statements on which way you should 
> lean because there are good counterexamples in both "camps" so to speak.

Properly matching people's expectations is a lot more important than 
whatever counterexamples may exist.

-- 
Loïc Hoguin
https://ninenines.eu