RFC Backwards-compatibility scheme (guidelines, not policy)

[phadej]

Continuation of #4981

We shall make possible to do most tasks without build-type: Custom. It's a can of worms. I don't mention acme-mutable-package. Given that, build-type: Custom should be a rare case in the long run, so I wouldn't use too much resources to keep backward compatibility in Cabal the lib. (The most problematic case is that new cabal-install should be able to talk to old Setup.hs).

Given that, we should have cabal-install building Custom packages with old Cabal in repository, that might be tricky to setup though. @ezyang can cabal-testsuite do that, i.e. use system's Cabal lib, in that particular test?

However, we shouldn't deliberately break things. I think aiming to only grow the API is good.

Yet, as an example, license field will change next week (See #4887, my first point). #2547 is soon three years old issue. Here my point is: changing the type of rewriteFile isn't a as big thing as AMP, FTP or SMP, which are well planned, with clear schedule when things will happen. template-haskell breaks a little every GHC release, why cannot Cabal?

Also as #4997 shows, FlagAssignent being now opaque breaks current idris setup script, not badly - but breaks anyway.

Back to grow the API. To be clear: I like rewriteFileEx, because of it, I don't need to do changes in cabal-doctest right now. However, API cannot grow indefinitely. My proposal for such type signature changes:

• in version X
  • introduce foobarEx with new signature
  • deprecate foobar with a message: Use foobarEx, because . foobar will change its type in Cabal-X+N
• in version X+N
  • Change type of foobar to new signature
  • deprecate foobarEx with a message: foobarEx was a compat name in Cabal-X -- Cabal-X+N. It will be removed in `Cabal-X+M
• in version X + M
  • remove foobarEx

IMHO, N=1, M=2 would be enough.

That's already heavy process! Yet, I'll go thru {-# DEPRECATED #-} pragmas today, and amend messages with: this function will be removed in Cabal-3.0 (estimated: Oct 2018) https://github.com/haskell/cabal/milestone/42

---

In Ubuntu

• trusty, 14.04LTS: cabal-install-1.16
• xenial, 16.04LTS: cabal-install-1.22
• artful, 17.10: cabal-install-1.24.0.3 THIS IS VERY BAD, as it may enter
  18.04 LTS - can we do something about this?

In Debian:

• jessie: cabal-install-1.20.0.3
• stretch: cabal-install-1.24.0.1
• sid: 1.24.0.2 !!!

So I guess we have to keep 1.24 in mind for a while, when developing Cabal the lib. We cannot tell all users to update their cabal-install, luxury stack has!.

[phadej]

Note: we also have http://cabal.readthedocs.io/en/latest/misc.html#stability-of-cabal-interfaces, but I'm not sure that page is very true.

[phadej]

Comments: The goal of the proposal is to define the guidelines (i.e. not strict policy) how to deal with breakages in custom-setup-tests: #4997.

Also to give a recommendation how to name such transient functions (which are there only for legacy reasons), Ex seems to be used across codebase, e.g.

withTempDirectory :: Verbosity -> FilePath -> String -> (FilePath -> IO a) -> IO a
withTempDirectory verbosity targetDir template f = withFrozenCallStack $
  withTempDirectoryEx verbosity defaultTempFileOptions targetDir template
    (withLexicalCallStack f)

withTempDirectoryEx :: Verbosity -> TempFileOptions
                       -> FilePath -> String -> (FilePath -> IO a) -> IO a

So for the future Ex might be bad suffix choice, for something to be removed later. I'd avoid using prime too. A variant would be to change the guidelines to remove foobar, and leave foobarEx in place. That's however non-sustainable, as we might need foobarExEx

[23Skidoo]

Related: #3788, #3922.

[23Skidoo]

artful, 17.10: cabal-install-1.24.0.3 THIS IS VERY BAD, as it may enter 18.04 LTS - can we do something about this?

I think we should recommend Ubuntu users to switch to @hvr's PPA. Versions in official repos have always been ancient, usually lagging behind Debian. Also we should add back the update reminder removed in #2089, but make it possible to disable it via both a compile-time flag and a ~/.cabal/config setting.

[phadej]

To make it clear: I don't want such guidelines, Starting with cabal-install-1.24 we can reliably use CPP in Custom setup scripts, so just refactoring as needed is easier, than to try to draw a line where to compat and where to not.

Also: #3600

So alternative proposal is simply: Cabal-the-lib doesn't have any stronger guarantees about API breakage than PVP.

Note: this discussion is triggered by rewriteFile which @ezyang rewrote twice! But it's easy to compat in both cabal-doctest and idris. We can be nice and give heads up to the maintainers (as #4997 will tell us if we break them). People seems to be ok with FlagName becoming opaque e.g.

History note The original rewriteFileEx was introduced, because breaking change were done late after GHC freeze (RC was out), with some Kmett's package already having new releases on Hackage. That was bad, we want to prevent that. But let's not make in-between-version development too rigid.

[phadej]

Also seems that http://cabal.readthedocs.io/en/latest/misc.html#stability-of-cabal-interfaces if from time before custom-setup stanza. So we have really reconsider it.

[23Skidoo]

I'm okay with removing DEPRECATED stuff in 3.0. I'd love to just drop *Ex and ' suffixes, but requiring everyone to add them first and then changing the name back is a bit silly. The ExEx thing never happened in practice, I'd solve it by adding a version that takes an extensible FooParams structure a-la #3600 and call that something like fooParams.

The BC policy we seem to be following in practice is "try to preserve BC unless it's too costly" -- so, a softer version of "PVP guarantees". I think we can add a rule that when someone adds a DEPRECATED pragma, it should mention the future release number in which the entity will be removed. Then the release manager can grep for DEPRECATED and remove entities that are scheduled to die in the next release.

The stability page should mention/link to setup-depends.

[23Skidoo]

I'd love to just drop *Ex and ' suffixes, but requiring everyone to add them first and then changing the name back is a bit silly.

Perhaps we can still do that, if an impact assessment (see https://github.com/23Skidoo/all-custom-setups) shows that only a small number of packages will be affected.

[phadej]

Looks like there's also #3573. Yearly topic!

[phadej]

I guess, Cabal is just a library. Use version bounds.