Deprecate new- prefix

[geekosaur]

Describe the bug
With removal of these prefixes from the documentation about to land (#9090, #9096, #9100), it's time to add deprecation messages on their use. After discussion on Matrix, we're tentatively eyeing 3.12 for addition of the deprecation messages and 4.0 for removal.

[ulysses4ever]

@Mikolaj @gbaz @fgaz @andreabedini how does it sound to you?

[andreabedini]

As I commented in #9107 (comment), I think splitting the change to one command at the time could be a simpler and quicker approach. AFAIK the big v1-to-v2 change arise from the different behaviour of install and perhaps some difference in the behaviour of build. I would need to go throught he issue tracker to be sure.

My drive is not much the user experience (v1 commands can be hidden, and temporarily left to power users who cannot yet find a v2 equivalent (for some generous appropriate definition of temporarily)) but driven by their side effect in the code base. It is difficult for me to figure out which code paths belong to v1, to v2, and which are shared between the two.

Perhaps someone with more experience could reorganise things in cabal-install so that the presence of v1 commands does not affect our ability to make changes.

[andreasabel]

new- prefixes, yes, certainly should go, because what was new in the past isn't new today.

However, I see no advantage in removing the v2- prefixes (as alternative to no prefix).
There are clear disadvantages:

• tutorials etc from all over the web have to be updated or will simply stop to work
• scripts need to be updated or will simply stop to work

If someone can explain me what the hard advantages of removing the v2- prefixes are that could counter the apparent costs for the ecosystem...

[ulysses4ever]

@andreasabel thanks for opining. I don't think this issue proposes removal, although it mentions removal in passing. Let's discuss just deprecation notices.

I understand you're fine with deprecation notices for the new- prefix. How do you feel about having deprecation notices for v2- prefix? Personally, I don't feel strong about it either way, but the prefix looks weird to me given that we're using cabal 3 these days (it made more sense in the era of cabal 2). I think it'd be quite prudent to tell the user that the prefix serves no purpose these days.

[andreasabel]

Well this issue is about deprecation in 3.12 and removal in 4.0.
I am not opposed to deprecation warnings, but what purpose do they serve if there is no removal planned?

I understand v1 to be the version 1 of the cli and v2 to be the version 2 of the cli, which need not be identical to the cabal version.

Suppose in 10 years there will be another revolution in build philosophy (God beware!) and a need for v3 commands. Then, having retained the v2- command names would be beneficial.

[geekosaur]

I'd've thought in that case removal of v2 would have been mildly annoying since they'd have to come back, but removal of new beneficial since they would be changing meaning but will have been free for reuse for years.

[Mikolaj]

Deprecation without a prospect of removal has no teeth. Good remark about the tutorials, though. However, I expect, long before the mythical 4.0 release comes, any cabal tutorial on the web that mentions v2- would be highly suspect of peddling outdated information and worth warning about (via the deprecation message in the v2- commands) and eventually blocking [edit: users can install old cabal, after all, and it's probably safer that way, especially for scripts]. The same for any ancient enough script. And if that's not the case, we can postpone the removal to the ultimate 5.0 release, the crown of our achievement.

I'd rather ask if we are not printing the deprecation messages too early. But I think our changelog since v2- has been replaced by empty prefix is long enough that the warning brings more potential benefit than annoyance. If not, let's wait one more year. But I'd rather annoy users about progress than give an impression of a non-curated API and stalled development.

[ulysses4ever]

Deprecation without a prospect of removal has no teeth.

Respectfully, I disagree. Deprecation will nudge people in the right direction — to not use the prefixes. This will gradually make most people realize that you don't need them (today many people are still worried that skipping the prefix can be harmful). When we see that it worked, we can open a separate issue about removal. This issue should have been focused on deprecation notices only.

I'm surprised that it's debated so much: we all agree (I thought) that local builds is the way to go today by default (there are rare sharp edges that may force you otherwise). So there's no reason to use the cryptic prefixes (I hate v2 especially, as it has no excuse in Cabal 3 imo). Also no reason to have newcomers asking "what happens if we don't put v2" all over again.

Ah,

I understand v1 to be the version 1 of the cli and v2 to be the version 2 of the cli, which need not be identical to the cabal version.

well, respectfully, it's a silly way to version CLI in my opinion, and therefore I think we should axe it. I'd be very curious to hear about precedents of using this way of versioning CLI.

---

Back from ranting mode, @Mikolaj, I didn't quite get your stance: do you want deprecations or not?

[Mikolaj]

@Mikolaj, I didn't quite get your stance: do you want deprecations or not?

I'm for deprecation for both new- and v2- prefix. I can be convinced we need to wait a year with that, because our functionality is still close enough to the one when v2- has been introduced (or when it was replaced by no prefix), so the risk tutorials and scripts using v2- are critically incompatible with current cabal is low.

[gbaz]

As I recall, the original plan was never to remove the v2- prefix. I'm open to eventual deprecation to nudge people away, but I would only want that once v1 commands are fully removed.

As it stands, as long as v1 commands exist, explicitly using v2 to disambiguate is a valid pedagogical methodology and there's no reason to discourage it.

[ulysses4ever]

That settles it for v2 prefixes then.

should we reword the title and OP to mention only “new” prefixes and start working on deprecation notices for then?

[mouse07410]

That settles it for v2 prefixes then.

should we reword the title and OP to mention only “new” prefixes and start working on deprecation notices for then?

Yes.

[andreasabel]

@gbaz wrote:

the original plan was never to remove the v2- prefix.

Good plan!
One can think about the prefixes in the following way: With v1- and v2- (and prospectively new versions that our grandchildren will add) one uses qualified names to identify the respective command, and without the prefix, unqualified, one uses the current default API.

[Mikolaj]

Delaying the deprecation warning of v2- until v1- are gone, or at least until they get the deprecation message saying "will likely be deleted in the next major release", is fine by me. Indeed it's silly if v2- gets a warning and v1- is mum.

[tjakway]

I'm in favor of keeping the v2- prefix indefinitely, for both practical and semantic reasons. "cabal install" is really an alias for cabal v2-install in modern cabal and cabal v1-install in old cabal. Keeping prefixes means there's always a canonical label for the behavior a user needs. If at some point there are other versions of some commands then tools that call cabal will be able to specify exactly which version they want. Otherwise they need to keep a table of what-each-command-does-for-which-cabal so they know that "cabal do-xyz" is the right "do-xyz". I don't think this is that crazy considering the v2 transition is taking >3 years.

Also, the version 2 commands will forever be known to people talking about them as "the version 2 commands", at least when they want to be specific. Keeping the prefix is in line with that. Guides can be written without telling people to look at tables of commands for their cabal version. If anyone ever begrudges the space in --help they could be listed under a "--show-options" flag instead.

To be clear, I think the v2- prefixed commands should be kept but that the non-prefixed commands can be changed. Like a symlink where the binaries are v1-install or v2-install and the link dest is "install". At least that's how I've always thought about it...

[ulysses4ever]

We're going in circles: this issue was never about v1, and it's not about v2 anymore either (check out the new title).

Please, express your opinion on deprecation notices for the new- prefix with no commitment to the removal of that prefix.

I'm +1.

[andreabedini]

+1 from me

[gbaz]

I think there's no objection to deprecation of the new- prefix and a consensus for it.

[mouse07410]

We can deprecate new-. Besides, it's bound to become ambiguous at some point in time.

And we leave v1- and v2- alone.