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?