Examples for migrating from commander to transient

[raxod502]

I recently upgraded to Projectile 3, and the migration guide https://docs.projectile.mx/projectile/upgrading_to_projectile_3.html has this to say:

The single-key "Commander" (projectile-commander and def-projectile-commander-method) is gone. Its replacement is projectile-dispatch, a transient menu bound to s-p m. A prefix argument on project switch (C-u s-p p) also opens it.

If you defined your own commander methods, add them to the dispatch transient instead (see transient-append-suffix and the projectile-dispatch definition).

This is great, but rather lacking on details about how exactly to use transient-append-suffix to amend projectile-dispatch.

My original code was:

(use-package projectile
  :config
  (def-projectile-commander-method ?\C-m
    "Find file in project."
    (call-interactively #'find-file)))

It took me quite a while to figure out that this was what I had to replace it with:

(use-package projectile
  :config
  (require 'transient)
  (projectile--dispatch-define)
  (transient-insert-suffix 'projectile-dispatch "f"
    '("RET" "manually" find-file)))

In particular:

• It wasn't clear that I needed to pass the symbol projectile-dispatch to PREFIX of transient-append-suffix. I could make a guess, but the Projectile docs call projectile-dispatch a "menu", not a "prefix" or "command".
• It wasn't clear what to select for LOC of transient-append-suffix. The previous code didn't have any such argument, it just added a new keybinding. Once I figured out I needed to specify an existing transient command in the same menu, it took some guessing to figure out that it should be another keybinding as a string, instead of (for example) one of the heading names shown in transient-define-prefix. I also had to figure out that I needed to use a different function transient-insert-suffix if I wanted to put my entry at the beginning instead of at the end.
• I was unable to use transient-insert-suffix out of the box at all, because Projectile seems to be defining the transient menu dynamically, using the projectile--dispatch-define helper. By default, you get an error when trying to use transient-insert-suffix. So I had to manually call projectile--dispatch-define after loading Projectile, which seems wrong. That didn't work either out of the box because Projectile doesn't load Transient until after projectile-dispatch is called, so I also had to load Transient manually, too. Maybe there is a hook I am supposed to run these customizations on? I didn't see one mentioned in the migration guide.

It would be really helpful if the migration guide included concrete before-and-after examples on replacing def-projectile-commander-method with Transient commands.

[bbatsov]

Great feedback! I totally agree we should clarify this in the docs and I'll see what I can do about this.

[bbatsov]

See #2195

[raxod502]

Awesome! Great improvement, thanks!