Update CLI documentation for status and reset commands (resolves #4771)

[Wryhder]

Current behavior

The docs for the status and reset commands are missing code examples and a long about section.

Proposed changes

Resolves #4771

The modifications are as suggested in this comment.

Checks

• All commits in this Pull Request are signed and Verified by Github.
• All commits in this Pull Request follow the Ockam commit message convention.
• There are no Merge commits in this Pull Request. Ockam repo maintains a linear commit history. We merge Pull Requests by rebasing them onto the develop branch. Rebasing to the latest develop branch and force pushing to your Pull Request branch is okay.
• I have read and accept the Ockam Community Code of Conduct.
• I have read and accepted the Ockam Contributor License Agreement by adding my Git/Github details in a row at the end of the CONTRIBUTORS.csv file in a separate pull request to the build-trust/ockam repository. The easiest way to do this is to edit the CONTRIBUTORS.csv file in the github web UI and create a separate Pull Request, this will mark the commit as verified.

[Wryhder]

@adrianbenavides Hi! Could you please address these?

1. Is this expected behaviour? Some information isn't included in the output of ockam status until after some other command is executed. For example, I ran ockam message send hello --to /node/n1/service/uppercase successfully after starting the node, but only after running ockam service list --at n1 did the Transport, Secure Channel, and Services information populate. Also, only after running ockam space list was subscription info included in the status output.
2. Please help with any needed clarifications for this comment.
3. Please review the long about for status in my commit. Is that useful information or unnecessary duplication? Should anything in particular be elaborated on, and in what way?
4. When might it be useful or necessary to do a reset (asides maybe discarding after initially testing or trying things out)?

[adrianbenavides]

Please review the long about for status in my commit. Is that useful information or unnecessary duplication? Should anything in particular be elaborated on, and in what way?

I think I answered this in the review. Let me know if you have any further questions!

When might it be useful or necessary to do a reset (asides maybe discarding after initially testing or trying things out)?

The reset command should be advertised as a dangerous / "use with caution" command really (we should display this in the command docs somehow), as it's used to remove all the local state permanently. Usually, the user will use more granular delete commands (e.g. node delete, identity delete, space delete, ...). But, yeah, as you said, the reset command is mostly used in examples, or while developing, to clean up things easily and start from scratch.

[Wryhder]

Please review the long about for status in my commit. Is that useful information or unnecessary duplication? Should anything in particular be elaborated on, and in what way?

I think I answered this in the review. Let me know if you have any further questions!

When might it be useful or necessary to do a reset (asides maybe discarding after initially testing or trying things out)?

The reset command should be advertised as a dangerous / "use with caution" command really (we should display this in the command docs somehow), as it's used to remove all the local state permanently. Usually, the user will use more granular delete commands (e.g. node delete, identity delete, space delete, ...). But, yeah, as you said, the reset command is mostly used in examples, or while developing, to clean up things easily and start from scratch.

@adrianbenavides Thanks a lot for your review! And apologies for the delay on this PR. I'll resume work on it within the next couple of days.

[Wryhder]

@adrianbenavides I've made the suggested modifications. Please take a look again when you get the chance. Thank you!

[Wryhder]

The reset command should be advertised as a dangerous / "use with caution" command really (we should display this in the command docs somehow), as it's used to remove all the local state permanently. Usually, the user will use more granular delete commands (e.g. node delete, identity delete, space delete, ...). But, yeah, as you said, the reset command is mostly used in examples, or while developing, to clean up things easily and start from scratch.

@adrianbenavides What about a superscript-type tag like this (saying "unsafe" or similar), in addition to the warning-level notification in the doc itself?

[adrianbenavides]

Awesome, thanks @Wryhder ! I'll take a look as soon as possible 🙏

[adrianbenavides]

@adrianbenavides What about a superscript-type tag like this (saying "unsafe" or similar), in addition to the warning-level notification in the doc itself?

That would be nice indeed. We do something similar with the "preview" tag (here and here) if that's useful.

[adrianbenavides]

@Wryhder I've left some comments to improve the output a little bit but it looks nice, thanks for taking the time with this!

One final recommendation: make sure you run cargo clippy and cargo fmt and squash all the commits into a single one once you have everything ready.

[Wryhder]

@Wryhder I've left some comments to improve the output a little bit but it looks nice, thanks for taking the time with this!

One final recommendation: make sure you run cargo clippy and cargo fmt and squash all the commits into a single one once you have everything ready.

@adrianbenavides I've made the modifications, run cargo clippy and cargo fmt, and squashed the commits. Please take a look when you get the chance. Thank you for your help with this!

[Wryhder]

@adrianbenavides What about a superscript-type tag like this (saying "unsafe" or similar), in addition to the warning-level notification in the doc itself?

That would be nice indeed. We do something similar with the "preview" tag (here and here) if that's useful.

@adrianbenavides This should be in a new PR, yes?

[adrianbenavides]

Hey @Wryhder just left some minor changes and we are good to merge!

[adrianbenavides]

@Wryhder there are a couple of CI jobs failing:

• the commit linter is complaining about the CLI word being in uppercase. You can just amend it using cli instead.
• the editorconfig linter is complaining about a couple of missing newlines at the end of the files. Take a look here for more details

[Wryhder]

@Wryhder there are a couple of CI jobs failing:

• the commit linter is complaining about the CLI word being in uppercase. You can just amend it using cli instead.
• the editorconfig linter is complaining about a couple of missing newlines at the end of the files. Take a look here for more details

@adrianbenavides I added the final newlines and modified the commit message while squashing the commits. I've successfully changed the commit message but the newlines seem to have disappeared. I'm trying to figure out if it's my editor or what else.

[Wryhder]

@adrianbenavides There are still a couple of CI jobs failing. One is about my commit not being signed and verified. Wanted to let you know I'll take a look by weekend.

[Wryhder]

@adrianbenavides I think this is good to go now. Please confirm when you get the chance. Thanks very much for your time and help with this.

[adrianbenavides]

Thanks @Wryhder for taking care of that! It all looks good now. The failing CI job is not related to this PR, and will get fixed on develop soon. We'll merge your PR after that is fixed. Thanks again for the time you put into this 🙏

[adrianbenavides]

Hey @Wryhder ! I've created a PR here with your commit fixing the conflicts for you. I've cherry-picked your commit, so you will get all the credit for your contribution.

Sorry again for the delay. We've been pretty busy working in the latest release and I didn't have the time to come back to this.

I'm closing this PR in favor of the other.