RFC: A plan to gradual removal of v1- commands

[Oleg Grenrus]

Dear development aware cabal users

I request you to comment on a plan to gradually remove `v1-` commands.

Some users have commented about the notice in `v1-` commands' `--help`:

  It is a legacy feature and will be removed in a future release of
  cabal-install. Please file a bug if you cannot replicate a working v1- use
  case with the nix-style commands.

This note is vague, and indeed we don't have any concrete plan *when*
something will be removed.

Lets have one.

At the moment, in upcoming `cabal-install-3.4.0.0` we have following
commands:

  v1-build          Compile all/specific components.
  v1-configure      Prepare to build the package.
  v1-repl           Open an interpreter session for the given component.
  v1-run            Builds and runs an executable.
  v1-test           Run all/specific tests in the test suite.
  v1-bench          Run all/specific benchmarks.
  v1-freeze         Freeze dependencies.
  v1-haddock        Generate Haddock HTML documentation.
  v1-exec           Give a command access to the sandbox package repository.
  v1-update         Updates list of known packages.
  v1-install        Install packages.
  v1-clean          Clean up after a build.
  v1-doctest        Run doctest tests.
  v1-copy           Copy the files of all/specific components to install
locations.
  v1-register       Register this package with the compiler.
  v1-reconfigure    Reconfigure the package if necessary.

I propose the following plan:

In 3.4.0.0 (to be officially released in a week from GHC-9.0.1 release,
i.e. soon)
we have already removed `v1-sdist`, as `v2-sdist` have completely
subsumed the
functionality, yet the interface is slightly different.

In 3.6.0.0 (to be release around GHC-9.2) we will remove

   - v1-update:  the v2-update should already completely subsume the
functionality
                 (but this have to be checked)
   - v1-doctest: is a commeand which never worked properly
   - v1-exec:    its description mentions sandbox package repository,
                 as sandbox are already removed, v1-exec has no use

In 3.8.0.0 we will remove what I'd call "interactive" development
commands:

   - v1-freeze
   - v1-bench
   - v1-reconfigure
   - v1-repl
   - v1-run
   - v1-clean

These are commands which I don't expect to be heavily used in scripts.

That would leave us with what I consider essential commands.
I think these are sufficient if `v1-` commands are used in some
bigger build process. (Though, I'd suggest to use raw `./Setup`)
This can be removed in 3.10 (or more conservatively in 3.12).

   - v1-build
   - v1-configure
   - v1-haddock
   - v1-test
   - v1-install
   - v1-copy
   - v1-register

These commands will be removed in 3.12 (skipping the 3.10).

In summary:

  v1-sdist          now          3.4
  v1-build          two years    3.12
  v1-configure      two years    3.12
  v1-repl           one year     3.8
  v1-run            one year     3.8
  v1-test           two years    3.12
  v1-bench          one year     3.8
  v1-freeze         one year     3.8
  v1-haddock        two years    3.12
  v1-exec           6 months     3.6
  v1-update         6 months     3.6
  v1-install        two years    3.12
  v1-clean          one year     3.8
  v1-doctest        6 months     3.6
  v1-copy           two years    3.12
  v1-register       two years    3.12
  v1-reconfigure    one year     3.8

I should mention that we don't test any of `v1-` commands anymore.
The code is there, and if it works it is good, but if it doesn't,
we wont actively pursue fixing it (rather concentrating on whatever
issues are holding you from migration to v1-build).

I would value comments whether the list for 3.6
(v1-update, v1-doctest, v1-exec) is found controversial.
Very rough estimate is that 3.6 will be released early 2021,
in about a half a year from now.

3.8 would happen a year from now. (Fall 2021)
3.12 where the v1-build is gone would happen in two years from now.
(Fall 2022)

Disclaimers:

I don't want to set the plan in stone.
In other words, "All rights reserved",
but we would avoid removing anything earlier than agreed.
Yet, it's impossible to predict the future,
and we might be forced to diverge from that plan.

The version numbers are informative,
3.10 could be 4.0, or the release schedule could be accelarated or
slowed down.
We will stick to the time based definitions.

- Oleg