Improve --help ux for Canton sandbox #12990
Conversation
fixes #12985 changelog_begin changelog_end
| Canton. To see options of the underlying Canton runner, use ``daml | ||
| sandbox -- -- --help``. | ||
| Canton. To see options of the underlying Canton runner, use | ||
| ``daml sandbox --canton-help``. |
There was a problem hiding this comment.
Should we rather consider going the git way and doing an help subcommand? I.e. daml help sandbox
There was a problem hiding this comment.
I don’t see how that helps. You still have help for the sandbox wrapper and for the underlying canton JAR. Git doesn’t have that issue git status --help and git help status are the same help text.
There was a problem hiding this comment.
I don’t see how that helps. You still have help for the sandbox wrapper and for the underlying canton JAR. Git doesn’t have that issue
git status --helpandgit help statusare the same help text.
Yes, but it doesn't have git status --status-help. I would agree with you if you could have daml sandbox --help. Right now as a user I would prefer to see the help text for Canton by typing that. I expect some confusion from users over using daml sandbox --help vs. daml sandbox --canton-help.
There was a problem hiding this comment.
A few comments to explain why we’re in this situation: Canton itself does not have any special sandbox mode or even a separate JAR. So we need some wrapper that turns Canton into a somewhat usable sandbox by specifying certain options and config files. This wrapper has to make some choices like ports. It also provides some UX niceties that people expect in sandbox and make it easier to migrate like options to turn on static time. The idea here is that in 95% of cases, you only ever need to interact with the wrapper directly and you don’t have to care that there is an underlying Canton JAR.
However, Canton has thousands of options and we clearly don’t want to replicate all of them in the wrapper. So for advanced usages you might need to look at the Canton help.
I fully agree that the UX isn’t great and somewhat leaks how things are implemented internally. I don’t really have a better suggestion though. We can try to parse Canton’s --help output and integrate it but that seems super hacky and is bound to fail in the future. We could make daml sandbox -- --help work but I’m not sure that’s really better (it still leaks implementation details of there being an underlying wrapper) and it’s not discoverable. --canton-help has the advantage that it shows up if you just type --help.
fixes #12985
changelog_begin
changelog_end
Pull Request Checklist
CHANGELOG_BEGINandCHANGELOG_ENDtagsNOTE: CI is not automatically run on non-members pull-requests for security
reasons. The reviewer will have to comment with
/AzurePipelines runtotrigger the build.