Isn't that just going to kill retrocompatibility with any program that refers to Pervasives explicitely?

It's only deprecated, not removed, so it should be fine.

Forcing a deprecation warning still seems annoying to me. How about toplevel Pervasives being a module alias to Stdlib? People are not going to suddenly name their modules Pervasives, are they?

Isn't a warning exactly what we want? Pervasives is a terrible name, and this is a chance to slowly get rid of it. A warning will make authors want to rename their module access without causing compilation errors.

How about toplevel Pervasives being a module alias to Stdlib?

This is independent from adding a warning or not. However, if Pervasives is an alias to Stdlib, then that mean that one might write Pervasives.List which might make things even more confusing.

I guess we need a compatibility package stdlib in opam so that we can use Stdlib with older compilers. I'll prepare that.

Ok, having a stdlib package gives a clear migration path and justifies the deprecation warning for me.

(it'd also be a foot in the door for detaching the stdlib from the compiler so it can evolve a bit… less… slowly, if I allow myself to dream)

A released open-source library should never have warnings as errors IMO, since it's impossible to predict what warnings will be added to the compiler in the future, and then your package will stop working. Warnings as errors is great for a closed, internal business environment, where exhaustive error checking is the highest priority.

This PR is getting a bit old. Is anyone willing to review it? If not, I'll just close it.

Thanks. I'm going to rebase it then

It's now rebased on trunk

PR to add a Stdlib module to stdlib-shims: ocaml/stdlib-shims#5

On a more general note I think that a good and user-friendly deprecation mecanism should allow both indicating the version in which an element gets deprecated and the actual minimal version a client of the library needs to support, so that no false positives are reported.

Agreed

The Library chapter of the Manual still talks about Pervasives in its opening paragraph, only to switch to Stdlib later on in the page (and mentioning that Pervasives is an alias). Quite confusing, and probably not what was intended?

@nobrowser I suggest submitting a distinct bug report, or a pull request with a fix.

Coming back to this PR with the hindsight of the discussion here, I'm wondering whether this was a good move, or just added to a feeling of 'too much backwards incompatibility'? Would it really hurt to have Pervasives be an alias to Stdlib? It would potentially keep a lot of old code compiling.

Just to clarify: my beef is not so much that Pervasives is still mentioned at all, but that some parts of the manual refer to Pervasives and others to Stdlib. I don't think anyone can reasonably maintain this is okay.

It seems to me that it is better to have a single name for things, Stdlib.x seems like the right name and deprecating Pervasives is the first step towards reaching this point.

Ideally, it would be great if the user could specify what version of the stdlib their code was written against. For instance, a user specifying that their code was written against the 4.02 version of the Stdlib would get no warning when using Pervasives, even when using OCaml 4.08. It's only when they decide to upgrade to the new stdlib that using Pervasives would trigger a warning, or even directly a hard error. This is how things work in Dune for instance.

It seems to me that it is better to have a single name for things

That's true, but it is also important, when lots of people are depending on a compiler to be stable, to be able to use their old code.

There is currently a perception among long-term devs that too many things are being changed in backwards-incompatible ways without strong reason. This isn't my feeling per se, but that sentiment is present in the community. If there's a way to get the new innovation while keeping backwards compatibility- in this case, having Stdlib, but also aliasing it to Pervasives so things keep compiling - that's a win in my book.

In the meantime, I think work on versioning mechanisms for everything should take place, including the stdlib and language grammar, so that we can make big changes without worrying about backwards compatibility as much.

I see. So the idea would be: we want to deprecate Pervasives, but we don't do it right now because it's too painful without more language support? Personally, that works for me. What do other OCaml developers think about it? It's a bit of back and forth, which is a bit annoying, but sometimes that's what you have to do.

BTW, aliasing Stdlib as Pervasives wouldn't work well as you already have Stdlib.Pervasives. We could have both though it's starting to be really confusing. Instead, we could simply remove the [@@@deprecated] attributes from Stdlib.Pervasives. New functions would go only in Stdlib and not Pervasives, which seems acceptable.

Instead, we could simply remove the [@@@deprecated] attributes from Stdlib.Pervasives. New functions would go only in Stdlib and not Pervasives, which seems acceptable.

I had been thinking about the latter option (removing the [@@@deprecated] annotation) given the amount of discussion this has produced. A variant of this could be to use a different alert than deprecated (eg deprecated_pervasives, disabled by default) so that those that really want to migrate to stdlib and be sure their code is clean of references to Pervasives can still do so.

Using a different alert seems like a good idea to me!

Users always rightly complain when things change, but I don't perceive the outcry people seem to be mentioning. It seems to me that trying to revert things now would be overreacting and will only bring in more churn and noise into the whole thing.

In a discussion that I fail to dig out somewhere on this project I think it was loosely agreed upon that the right way of deprecating features/names in favor of others given the current tooling situation was to:

1. Introduce the new feature/workaround and deprecate the old feature silently.
2. Wait for a few versions (e.g. for example until debian stable has the new feature), then start deprecating the older feature loudly via a warning, indicating in which version it will be removed.
3. Get rid of the deprecated feature when the version mentioned at the previous point is met.

This process would minimize the chances you'd actually have to live with warnings in your builds and let people with enough time to move on to upgrade their code bases.

Now in that particular case the "wait for a few versions" bit was not done but on the other hand there's a package (stdlib-shim) that allows to get rid of the warning in builds for code that needs to compile cleanly both pre and post 4.08. As such I don't think we should revert what has now gone in the wild. AFAIK no code is being broken, warnings are being produced.

Warnings are what entices people to move on. If they are hidden behind a special alert, then we will end up with what @gasche described here with safe-string.

The presence of stdlib-shims has made it very easy for me to port code to 4.08 without dropping compatibility. If anything, rather than going backwards, it would be even easier if dune or merlin just did the module renaming for me and promoted a candidate patch that could be promoted into the source tree :-)

Importantly, there has never been a case where I've been unable to perform the renaming from Pervasives to Stdlib and fix the warning (unlike, e.g. safe-string where a lot of thought had to go into the interface transition, and so it just took years).

If we could state somewhere (dune file) which ocaml version we wrote the package for (ie. not its compatibility), couldn't it just use stdlib-shims as needed? (The next step would be a package to handle different grammars-as-packages based on the targeted ocaml version).

So, @bluddy wants me to give my feedback on this. My feeling about this deprecation is that it was a bad idea, and that nothing in the stdlib should be deprecated ever without a very, very well thought out plan. Here we've faced the breakage of 100% of OCaml code that uses dune to compile (with the dev profile, of course, but breaking dev compilation is still a breaking change).

The thing is, this changed my stance on breaking my own libraries. I'm not sure I'll ever introduce containers 3.0 now, because breaking code is just too painful and unecessary. The only breaking changes I'm willing to accept are those that are necessary to fix bugs.
</rant>

Here we've faced the breakage of 100% of OCaml code that uses dune to compile (with the dev profile, of course, but breaking dev compilation is still a breaking change).

I think that you are rather facing a wrong default in dune here. I don't see a deep reason why dev builds should fail on deprecation warnings. Put the blame where it should be, a stock ocaml invocation won't fail on this and there may be a good reason for it.

The only breaking changes I'm willing to accept are those that are necessary to fix bugs.

I'm not sure such extreme positions are helpful in order to move on to improve the overall usability of the system. Note that Stdlib was actually introduced so that the system could be improved without breaking user code. Now as a matter of fact having both Pervasives and Stdlib is not a bug but needlessly confusing in the long term for the usability of the system so it seems better to plan for letting it eventually go.

I think that you are rather facing a wrong default in dune here.

100% agreed.

I agree that what done is done. No matter was it right or not. And rolling this back will be a huge mistake. But making a small plugin for dune, like cargo fix, would be a feature killer. After all in this case, if the project uses dune, it just adding a new line for stdlib-shims, or doing a simple text replace of Pervasives, less than 100 lines of code I believe.

I created an issue in Dune for discussing and tracking this: ocaml/dune#2563

The issue with the dune default is something that has been well discussed but rejected anyway. I agree that if dune had the right default then people wouldn't complain about deprecations so much and the stdlib could continue deprecating things at a relatively more aggressive pace.

I really don't think downstream tools and their opinions about which default ocaml flags should be enabled or not should dictate how things can or cannot be deprecated in the stdlib.

Again ocaml{c,opt} do not fail on this and there's a good reason for it.

I don't want to discuss the particular points that are made there but it seems to me that they are largely wrong from a usability point and code evolution perspective. First as @c-cube suggests
you certainly want all of your projects to compile out of the box when you want to try or switch to the latest version of the compiler -- that moment may not be the time for you to handle deprecations warnings you may be interested in testing other things. Second by teaching people to manually silence them if they can't handle them asap you make it easier to forget about them which will end up biting them later.

If you never have deprecation warnings treated as errors, then even after someone has done the job of fixing deprecation warnings nothing prevents you from writing new code that has deprecation warnings.

The compiler doesn't treat deprecation warnings as error to maximise backward compatibility and dune does that as well in release mode. However, the compiler itself is built with a lot of warnings treated as errors, including deprecation warnings. This is because this generally improves the quality of the code as developers have no choice but to fix their warnings right from the start. Dune is simply following this idea by treating many warnings as errors by default in development mode.

However, I agree that there is a case that is not well handled in Dune at the moment; the case when one wants to test their project with a new compiler before they have decided to properly switch to the new compiler. This can be discussed further here.

Regarding the current discussion, it seems worth to me to split the problem in two:

1. many projects reference Pervasives in their code, so deprecating Pervasives causes a lot of people to be forced to take action
2. Pervasives is mentioned in many books, tutorial, documents, etc...

Regarding 2, I suggest that we simply keep the deprecated name Stdlib.Pervasives forever, even if it just becomes an empty module at some point. This way, someone reading a old book will always be able to easily figure out how to adapt code snippets so that they work with newer compilers.

Regarding 1, I agree that this is unfortunate. At the same time, even without automated tools upgrading the code is relatively simple and shouldn't take long. Does anyone disagree on this point?

Given all this, it doesn't seem worth to me to un-deprecate Pervasives.