Era-sensitive command structure

[newhoggy]

Changelog

- description: |
    Era-sensitive command structure
  compatibility: breaking
  type: feature

Context

Adding top-level era command groups avoids some of the problems posed by era flags. That is optparse-applicative does not allow for any dependencies between two command line options, so it is not possible for the era flag to control the validity of other flags. To allow for the chosen era to control the validity (and presence) of flags so that flags that are not relevant for the era don't appear and are invalid, the eras are promoted to top-level command groups.

This is what the help looks like now:

cardano-cli
cardano-cli - General purpose command-line utility to interact with
cardano-node. Provides specific commands to manage keys, addresses, build &
submit transactions, certificates, etc.

Usage: cardano-cli
                     ( shelley
                     | allegra
                     | mary
                     | alonzo
                     | babbage
                     | conway
                     | latest
                     | experimental
                     | Legacy commands
                     | byron
                     | ping
                     | version
                     )

Available options:
  --version                Show the cardano-cli version
  -h,--help                Show this help text

Available commands:
  shelley                  Shelley era commands
  allegra                  Allegra era commands
  mary                     Mary era commands
  alonzo                   Alonzo era commands
  babbage                  Babbage era commands
  conway                   Conway era commands
  latest                   Latest era commands (Babbage)
  experimental             Experimental era commands (Conway)

Legacy commands
  address                  Payment address commands
  stake-address            Stake address commands
  key                      Key utility commands
...

And inside governance sub-command for babbage:

$ cardano-cli babbage governance
Usage: cardano-cli babbage governance pre-conway

  Era-based governance commands

Available options:
  -h,--help                Show this help text

Available commands:
  pre-conway               Pre conway era governance command

And inside governance sub-command for conway:

$ cardano-cli conway governance
Usage: cardano-cli conway governance post-conway

  Era-based governance commands

Available options:
  -h,--help                Show this help text

Available commands:
  post-conway              Post conway era governance command

The latter two examples show how command availability can switch on era.

Checklist

• Commit sequence broadly makes sense and commits have useful messages
• The change log section in the PR description has been filled in
• New tests are added if needed and existing tests are updated. These may include:
  • golden tests
  • property tests
  • roundtrip tests
  • integration tests
    See Runnings tests for more details
• The version bounds in .cabal files are updated
• CI passes. See note on CI. The following CI checks are required:
  • Code is linted with hlint. See .github/workflows/check-hlint.yml to get the hlint version
  • Code is formatted with stylish-haskell. See .github/workflows/stylish-haskell.yml to get the stylish-haskell version
  • Code builds on Linux, MacOS and Windows for ghc-8.10.7 and ghc-9.2.7
• The changelog section in the PR is updated to describe the change
• Self-reviewed the diff

Note on CI

If your PR is from a fork, the necessary CI jobs won't trigger automatically for security reasons.
You will need to get someone with write privileges. Please contact IOG node developers to do this
for you.

[newhoggy]

These are the new command groups.

Note that byron is intentionally missing because there already is a legacy byron command group.

latest currently set to byron and experimental set to conway.

[newhoggy]

The pre and post conway run functions receive a witness which constrains which era the run function applies to.

[newhoggy]

Era witnesses are summoned from the era like this. feature is the witness.

[CarlosLopezDeLara]

Perhaps instead of "Legacy commands" something like "Common commands"

[Jimbo4350]

So rather than all encompassing "pre/post-conway" commands we should pattern match on the relevant ShelleyToBabbage era/ ConwayOnwards era values and render the appropriate command name.

[newhoggy]

Yeah, post-conway is a place holder example. It should be replaced with a command.

[Jimbo4350]

I'm skeptical of having an experimental set of commands, it will add more churn for not that much benefit. We should just print something to stdout if a command or group of commands is experimental.

[newhoggy]

experimental isn't strictly necessary because users wanting to test Conway can still use conway. The cost of having experimental isn't that high though since it is effectively equivalent to conway.