Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[RFC] Expose cabal-install as a library. #5476

Open
wants to merge 1 commit into
base: master
from

Conversation

Projects
None yet
5 participants
@23Skidoo
Copy link
Member

commented Jul 31, 2018

This has been requested multiple times in the past, and now that the releases of Cabal and cabal-install are more frequent, the downsides are IMO not as big as before.

To make the maintenance easier, I propose that we don't require @since annotations in lib:cabal-install and don't go out of our way to support clients that want to be compatible with multiple major releases of lib:cabal-install.

Additionally, this simplifies cabal-install.cabal a bit by removing the lib flag.

Fixes #1597.


Please include the following checklist in your PR:

  • Patches conform to the coding conventions.
  • Any changes that could be relevant to users have been recorded in the changelog.
  • The documentation has been updated, if necessary.
  • If the change is docs-only, [ci skip] is used to avoid triggering the build bots.

Please also shortly describe how you tested your change. Bonus points for added tests!

Expose cabal-install as a library.
This has been requested multiple times in the past, and now that the
releases of Cabal and cabal-install are more frequent, the downsides
are IMO not as big as in the past.

To make the maintenance easier, I propose that we don't require @SInCE
annotations in lib:cabal-install and don't go out of our way to
support clients that want to be compatible with multiple major
releases of lib:cabal-install.

Additionally, this simplifies cabal-install.cabal a bit by removing
the 'lib' flag.

Fixes #1597.

@23Skidoo 23Skidoo changed the title Expose cabal-install as a library. [RFC] Expose cabal-install as a library. Jul 31, 2018

@hvr

This comment has been minimized.

Copy link
Member

commented Jul 31, 2018

Does this mean we make no guarantees whatsoever to consumers of the library? I.e. every module is treated as "internal" and thus out of the scope of PVP versioning (and we do not maintain any API-level changelog; and are free to make non (EDITED) backward compatible changes w/o major ver bumps)? If not, I'm strongly against this.

Personally I was hoping we'd rather finally move to use internal sub-libs, and internally structure the code into a solver sub-lib and a non-solver sub-lib.

@23Skidoo

This comment has been minimized.

Copy link
Member Author

commented Jul 31, 2018

we do not maintain any API-level changelog;

Yes, this shouldn't be required.

and are free to make backward compatible changes w/o major ver bumps)?

I guess you meant "incompatible". No, we will support clients that set e.g. build-depends: cabal-install == 2.4.*. The idea is that if the major releases are more frequent, we will need to do less minor ones. If we desperately need to backport an API-breaking change for lib:cabal-install, we can do a major release of cabal-install only. We can advance lib:Cabal version numbers by bigger increments to keep them in sync with cabal-install.

@phadej

This comment has been minimized.

Copy link
Collaborator

commented Jul 31, 2018

cabal-install would be bad library breaking all the clients. I don't want to consider backwards compatibility at all.

Maybe expose parts though (public) sub-libraries

@23Skidoo

This comment has been minimized.

Copy link
Member Author

commented Jul 31, 2018

I don't want to consider backwards compatibility at all.

You'll only need to think about it when backporting a patch to a stable branch.

@quasicomputational

This comment has been minimized.

Copy link
Collaborator

commented Jul 31, 2018

I think this is a good idea. Having access to the solver and to non-ad-hoc rendering & parsing of configuration files are both fairly important to the wider tooling ecosystem. If compatibility breaks, it's better to find out at compile time than at runtime since users are having to parse --dry-run output to get at the solver (true story).

lib:ghc changes something every major version (doctest has the CPP to prove it), but having access to the guts of it is so valuable that a little bit of adaptation is fine; cabal-install isn't a boot library, so users might not even need to break the CPP out.

Also - how often do cabal-install releases from old stable branches happen, anyway? The only scenario I can imagine where we'd want to is when we've got a terrible bug affecting a recent release that was the last one before a significant behavioural change (so we can't expect users to upgrade major versions). That seems very much like the exception, not the rule.

@hvr

This comment has been minimized.

Copy link
Member

commented Jul 31, 2018

You'll only need to think about it when backporting a patch to a stable branch.

in other words, we won't bother backporting anymore ;-)

Also - how often do cabal-install releases from old stable branches happen, anyway?

if we do this, then they'll occur even less as the cost increases even more!

This pushes us into the support mode which demands that cabal users upgrade to latest cabal-install as soon as it's available; which means we should reenable the warning in cabal which reminds users to upgrade as soon as a newer cabal version is available in the index! Haskell Platform releases & distros should also adapt to this new scheme, and possibly ship with cabal versions which don't necessarily match the version of lib:Cabal bundled by GHC.

Having access to the solver and to non-ad-hoc rendering & parsing of configuration files are both fairly important to the wider tooling ecosystem.

As a data-point, I can tell you that the tooling I maintain will most likely not use cabal-install as a library even if it becomes available, even though I need exactly those things you mention. It'd take an intentionally designed library design for me to consider depending on it, rather than some arbtirary kitchen sink API which wasn't designed for public use by anyone else other than cabal-install.

@23Skidoo

This comment has been minimized.

Copy link
Member Author

commented Jul 31, 2018

@quasicomputational

Also - how often do cabal-install releases from old stable branches happen, anyway?

As you can see from http://hackage.haskell.org/package/cabal-install, 1.18, 1.20, and 1.22 had quite a few minor releases. But then the gaps between major releases were much longer.

@hvr

in other words, we won't bother backporting anymore ;-)

Yeah, the idea is basically to not make minor releases unless we absolutely have to, but instead cut major releases more frequently.

which means we should reenable the warning in cabal which reminds users to upgrade as soon as a newer cabal version is available in the index!

Well, we want to do this anyway. Can't find the ticket for some reason.

It'd take an intentionally designed library design for me to consider depending on it, rather than some arbtirary kitchen sink API which wasn't designed for public use by anyone else other than cabal-install.

See this as a (tiny) step towards that goal. Next steps would be to split the pure core out of lib:Cabal and the solver out of lib:cabal-install. Maybe we can achieve all of this in 3.0. Need to make a decision about the version scheme, more frequent release schedule should make that easier as well.

@BardurArantsson

This comment has been minimized.

Copy link
Collaborator

commented Aug 2, 2018

Beware Hyrum's law.

IMO, it would be much better to start with e.g. the solver (which is moderately stable, interface-wise I guess?) to try to gain a little experience in what expectations users will come to have.

It's one thing to say "we guarantee nothing", but it's quite another to actually stick to that when users are screaming at you...

@23Skidoo

This comment has been minimized.

Copy link
Member Author

commented Aug 3, 2018

It's one thing to say "we guarantee nothing", but it's quite another to actually stick to that when users are screaming at you...

Seems to work okay for GHC API. But we should clearly communicate our API stability guarantees to the users.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.