This issue is meant to track the migration progress and give some implementation guidance.

Status (31/31)

• auth in patch/59997806eead5e3b8adf117981493b434f940431
• block in patch/224efaaca8b13208f3d3beafcc37b2d229b13901
• checkout in patch/b6495653409be30de353a445602e2e5a0ac604d5
• clean in patch/2fa2dcf7b64e7d60a39fff050e9e4057ef41ea54
• clone in patch/c0bcf014517eee36c3693bd62601670410cfc6d2
• cob in patch/490dedd8f7520f12e1d0aba917e4103774e67605
• config in patch/dcbcb7e8bcc30d3f6ea97b3d338ede8bd96cbf81
• debug in patch/343073d3a5999d3c81a308bfeb5d7b727ec14e8b
• diff in patch/61f78b2ff73747b7f77b5cd9517ed1db183d4ff5
• follow in patch/947e68e86c577ac348e7292b6e0f07ce52f1ac2f
• fork in patch/e5416429d8e19b065b85ad9a5e3afcd8265f162f
• id in patch/9e45558dda40cf7e46739fef11b366d2060ecb1d
• inbox (claimed)
• init in patch/6719913fa5e596f5946e2a59141f31c4a5b51fcb
• inspect in patch/3097a313c10fb5800026755f0634634582f14aea
• issue in patch/976756d8bf1f4e157ec8c1dc6818f670f8b4d726
• ls in patch/8d79097f8ffa950245b46b3930da07e651a58821
• node in patch/77453b5ea69bc07aed212f9e0c91332c16295ea1
• patch in patch/f9f6791c0b080cfe449e2e0cc4d514c1f82f9e59
• path in patch/75520da0d6f3f2f8611ba8d944ae61047e66b19c
• publish in patch/f3496b1634707f7f42a0245f7ed1ed59b4de828e
• remote in patch/e9defa94038506c9187930ba82be10c4a888acc6
• seed in patch/2b9404287827fd5e4d0c9702cd6df8ebfda0758b
• self in patch/908c750d6434403903da44c5ec64d81f2bddf119
• stats in patch/5311080da9c756cea39d0c55b818f2243da8d0f2
• sync in patch/bc69c2c2c0b942166e7286576b50e05f80763076
• unblock in patch/9a9b58fa02db817cc4597c815908eacf5b936b6d
• unfollow in patch/01fde0e26aa0c735f89f78ed50efb1a284360038
• unseed in patch/06b4d4851c54d43d23cf38d8661b52b1526c353f
• watch in patch/b4b7e7eabad05d1b1272c6b2ba43d5c37e46f9fe
• rad itself

Migrating a command

• Command behaviour should not change. Do not add flags or change the semantics.
• CLI tests should not change. Adding new tests that cover the current behaviour is appreciated though.
• First, migrate arguments to clap only, touching as little code as possible. Do refactorings in small, subsequent commits only after.
• Make sure help and error coloring follows rad issue.
• Using one-liners for argument description is preferred.
• Attribute macro usage on commands and args should follow rad issue
• Argument values should be named consistently across commands, e.g. ISSUE_ID, PATCH_ID, REVISION_ID, etc.

A Step-by-Step Recommendation

Create ABOUT and LONG_ABOUT

1. Change pub const HELP: Help = ... to pub(crate) const ABOUT: &str = "<Help::description>"; and LONG_ABOUT: &str = "<Help::usage>", editing the usage to fit claps “long about”.
2. Remove LONG_ABOUT if it is empty or trivial.

Migrate from struct Options to struct Args

1. Remove use terminal::args::Args.
2. Change impl Args for Options to just impl Options.
3. Use LSP to rename Options to Args.
4. Annotate Args with #[derive(Debug, Parser)], adding use clap::Parser
5. Annotate Args with #[command(about = ABOUT, long_about = LONG_ABOUT, disable_version_flag = true)]
6. Do the actual migration by annotating members of Args. This is the part to really think about. Look at fn from_args closely.
7. Remove the whole impl Args block.

Create args module

1. Create a new file <command>/args.rs.
2. Move struct Args and all associated types, as well as const ABOUT and const LONG_ABOUT (if it exists) to the new module args. Fix imports.
3. Wire up new module in <command>.rs: Add mod args, pub use args::Args and pub(crate) use args::ABOUT.
4. Add unit tests if the command uses custom parsing logic via e.g. value_parser for types like RepoID or NodeId.

Wire up main.rs

1. Add a new variant for your command to enum Commands.
2. Search for “run_command_fn”, copy the match arm.
3. Search for the command you are migrating, replace its match arm.

Wire up help.rs

1. Search for “CommandItem::Clap”, copy the constructor.
2. Search for the command you are migrating, replace the CommandItem::Lexopt constructor with the CommandItem::Clap constructor you copied, and edit it to fit.