Timeline and plan for removing v1- legacy commands

[mpickering]

The v2- project based commands were introduced alongside the legacy interface in
2016. This family of commands introduced support for multi-package based workflows
and installation of packages into a global store.

The primary way which people use cabal today is via the v2- interface. Writing
a command without a prefix defaults to using the v2 command.

This document starts from the premise that

We want to remove the v1- family of commands, therefore we need a plan to achieve that.

rendered

[hasufell]

IMO, cabal has a track record of too eagerly breaking and removing things without any real plan forward and leaving users with the pieces, such as removing sandboxes.

Without a clear path forward on how to satisfy the user experience of imperatively managing dependencies ad-hoc, I feel the removal of v1 is premature.

Also see haskell/cabal#10098

I'm also interested on how v1 removal may impact users of copilot, @ivanperez-keera

[ulysses4ever]

I agree with the direction of the proposal, but it'd be great to evaluate how far we are from supporting v1-based workflows that are still in use. And for that, we'd need to create a list of such workflows, and for that we will need community input (as Julian's message above hints to). So, I'd suggest to fast-track community-facing interaction on this front.

In leu of community-backed issues with the v1→v2 transition, I once created a label in the cabal repo specifically for that:
https://github.com/haskell/cabal/issues?q=state%3Aopen%20label%3A%22re%3A%20v1-vs-v2%22
If people decide they want to go ahead with the plan (and the timeline in the proposal looks pretty ambitious to me), I suggest having a quick look at these.

[mpickering]

Thanks Julian and Artem for your comments.

From your replies, I want to make sure I understand correctly: are you both suggesting that the decision to remove v1- commands should follow from the consultation phase, rather than treating removal as a fixed goal from the outset? That distinction would help clarify how we frame the next steps.

@hasufell If you’re interested, I’d very much value your input in defining the task list and criteria for the consultation phase. I’ve tried to outline what counts as a “blocking” item in the proposal, but I’m not entirely sure from your comment how you see that scope.

My intention is for the task list to be as concrete as possible so that once we’ve identified specific workflows or use cases, we can clearly see when the necessary work has been completed. I’m also open to adjusting the timeline depending on what the consultation reveals.

[ulysses4ever]

are you both suggesting that the decision to remove v1- commands should follow from the consultation phase, rather than treating removal as a fixed goal from the outset?

No, I think the goal of removing v1- can be explicitly set initially, I fully agree with it.

It's just the timeline that I'm having hard time evaluating before understanding how far we are from fulfilling the v1-based workflows that are currently in use (if there are such workflows).

[Bodigrim]

A few years ago a timeline to sunset v1- commands was published at https://mailman.haskell.org/archives/list/[email protected]/thread/2VW2KJFVNL5OHG4SO33FCQMTMUXUN6QG/. No one challenged the plan, but also it was never executed.

A related discussion happened at haskell/cabal#9107. An interesting point which would be nice to address is that some Cabal maintainers do not feel that v1- commands are complicating the code base.

One user of v1- commands of utmost importance is hackage-server itself: its haddock builder still works through v1-install. Perhaps fixing this could provide more assurance that all existing workflows can be migrated to v2-.

(I'm personally in favor of dropping v1- interface for the sake of simplifying Cabal codebase)

[hasufell]

@mpickering I find the motivation simply lacking.

I don't think there's anything fundamentally wrong with the v1 interface. It is well defined: essentially Setup.hs + a solver.

I don't see what the end user gains from removing it.

And this is what I have a problem with: the discussion is around maintenance burden and nothing else, while we should discuss what type of interfaces cabal should have.

There's other ways to deal with maintenance burden. Ask the CLC to find more maintainers or recruit some yourself.

[andreasabel]

The threat of removal of the v1 interface is what got me engaged in cabal in the first place.
Why is it a threat?
Because v2 is not feature-complete over v1.
Especially v2-install isn't an adequate replacement of v1-install, it has fundamental flaws, and nothing has happened in the last >4 years to address them.

• [nix-local-build] Garbage collecting the store cabal#3333
• cabal install run immediately after cabal build unnecessarily rebuilds the project cabal#6919
• cabal v2-installed executables should be resilient against (partial) deletion of .cabal/store cabal#7221

Rather than removing v1, the energy should be directed towards making v2 feature complete.

[mpickering]

@ulysses4ever I agree that the consultation phases is the most important phase of this proposed process, and that what is learnt in the consultation phase will dictate the rest of the timeline. I'll update the proposal to reflect that.

@Bodigrim Thanks for that useful context. I will amend the proposal to include some of the links that you mentioned. I find myself agreeing in principle with your comment on the v1-freeze thread.

@hasufell
I agree that user requirements should guide the project’s direction.
The purpose of the consultation phase is to identify and understand actual v1 use cases so we can base decisions on concrete data rather than assumptions. The idea isn’t to remove functionality for its own sake, but to make sure existing workflows are properly supported before we take that step.

It would be really useful to assemble a clear list of active v1 users to consult directly. From the discussion so far, the main ones seem to be Andreas Abel, Ivan Perez, and Hackage’s Haddock builder. If there are others you’re aware of, please flag them. It would be good to make the consultation as thorough as possible.

@andreasabel Thank you for bringing up these issues that you feel are keeping you on using the v1- workflow. These are exactly the kind of things which will be very important information during the consultation phase of the proposal.

The goal of this timeline is to turn something which is implicit ("feature completeness of v2-" commands), into something which is explicit and can be tracked as a goal to work towards. That way the Cabal maintainers can work with important user's like yourself to prioritise which issues to resolve whilst also making progress on removing legacy interfaces.

[hasufell]

@mpickering I still think this issue is not framed well.

If we want to make v2 feature complete, then this is what the proposal should say in the motivation.

The fact that the motivation is "lets remove v1" and then wait for the community to intervene and say "but wait" is a bit of a rough way to go about this.