docs: add best practices about status

[dwilding]

This PR adds a section called "Handle status" to How to write and structure charm code.

Preview build

[benhoyt]

This seems a bit backwards to me: we start by telling them to use self.unit.status but then say the best practice is not doing that, it's actually using collect_unit_status. I think we should reverse that: recommend collect_unit_status with an example, but then say something like "if you need something more fine-grained, you can set the status directly with self.unit.status = ...".

[tonyandrewmeyer]

Agreed. I think I muddle the conversation in daily earlier in the week because I was behind on Matrix messages and didn't realise there were two questions. I think our conclusions were:

• collect-*-status is always the pattern we recommend. It's ok to not use it for simple cases, but we should always prefer it in our docs, even in simple cases like the tutorial, because it's better to start people on that track than potentially confuse them by switching later (and then there's the "when you do pass simple" question).
• If your charm is expected to have more than one unit, you probably want to also set the app status rather than leaving it to Juju.

I suggest what we do here is say that you should use collect-unit-status, except when you need the status to update during the hook, typically setting maintenance status or active status with a degraded service message. The example would be similar, but the active status would be done in a collect_unit_status handler.

[tonyandrewmeyer]

Agreed. I think I muddle the conversation in daily earlier in the week because I was behind on Matrix messages and didn't realise there were two questions. I think our conclusions were:

• collect-*-status is always the pattern we recommend. It's ok to not use it for simple cases, but we should always prefer it in our docs, even in simple cases like the tutorial, because it's better to start people on that track than potentially confuse them by switching later (and then there's the "when you do pass simple" question).
• If your charm is expected to have more than one unit, you probably want to also set the app status rather than leaving it to Juju.

I suggest what we do here is say that you should use collect-unit-status, except when you need the status to update during the hook, typically setting maintenance status or active status with a degraded service message. The example would be similar, but the active status would be done in a collect_unit_status handler.

[tonyandrewmeyer]

I think we need to extend this to explain that collect-status updates the status in Juju at the end of the hook.

[tonyandrewmeyer]

I was going to suggest that this link to Juju to explain how the status is chosen, but then when I found the relevant page I noticed that it's the same as the "see also" below. We probably don't want to link to the same page twice, even if one link is to a specific section. Any ideas on how to indicate that you'll find the info there? If not, I'm fine with this as-is.

[tonyandrewmeyer]

I like the best practice notes to be as small as possible, so that they'll be easier to consume in a single list of items to check. What do you think about removing the first sentence?

[tonyandrewmeyer]

I wonder if we can point out here (a small example with a comment?) that the charm can unconditionally observe collect-app-status because it'll only be emitted for the leader. That is, you can do:

framework.observe(self.on.collect_app_status, self._on_app_status)

Rather than needing to do:

if self.unit.is_leader:
    framework.observe(self.on.collect_app_status, self._on_app_status)