Comment 5 for bug 1981410

I was helping a colleague figure out juju debug-hooks today and it took me a very long time to realize that I completely misunderstood how it works.

I thought, because I had decided this was what I wanted, that I could run juju debug-hooks app/0 and get a place to invoke arbitrary hooks. Instead I had an empty root shell whose pwd was /home/ubuntu and whose environment didn't seem set up to support invoking hooks or actions.

Then I thought, well, I want to debug the config-changed hook, so let's run juju debug-hooks app/0 config-changed, which will surely do what I want. Same deal.

After a few minutes of pondering, a new tmux window popped up telling me that I could debug update-status, which is when the light dawned. (Clearly I gave up on the second command and tried the first one again!)

The text in the new window also linked to a document that explains this well: https://juju.is/docs/sdk/debug-a-charm

I think the following might be helpful:

1. Expand the juju debug-hooks summary to explain what it does and how it works, maybe:

    Summary:
    Launch a tmux session to debug hooks and/or actions as they occur.
    Whenever a hook or action is run, a new window will open in the correct context.
    By default, all hooks and actions will be debugged.
    Supply arguments to limit debugging to the given hooks and actions.

(That could use some editing, clearly!)

2. Print some text in window 0 explaining what will happen, and linking to the above document.