docs: clarify distinction between maintenance and waiting status

[benhoyt]

Per discussion with @jameinel, Maintenance means "I'm not ready because of work that I need to do", versus Waiting, which is "I'm not ready because of work that other things need to do".

Also clarify when you should use a message for Active, and make wording a bit more consistent between docstrings.

[tonyandrewmeyer]

I think this wording is definitely much better and it's clear on the meaning that the Juju team is attaching to these terms.

Two thoughts:

• I'm not entirely sure what status I would use if I was waiting for something external to the model to be available (an external API, for example). I suppose WaitingStatus, because I'm lower-case-i integrated with that service even though I don't have an upper-case-I Juju Integration with it.
• I think there's a lot of use of WaitingStatus in existing charms outside of this - if I just grep for WaitingStatus across the Canonical charms, there's a lot of other cases (waiting for leadership (maybe that's "other units", so ok?), waiting for K8s, waiting for config, waiting to join a cluster, waiting for container/storage/pebble, waiting for the workload to be ready, etc). I'm fairly sure that people have been using WaitingStatus to mean "I'm waiting for something" and MaintenanceStatus to mean "I'm actively doing something, please wait". Basically, what these juju docs describe, which doesn't really match the existing ops docs, or the ones proposed here, or the Juju source.

It's fine if we really want WaitingStatus to be specific to relations (and presumably the Juju team are the final word on that), and we can encourage people towards the use we want. I think we want to be aware of existing use, and also need to get the Juju docs updated to match this as well, though.

[benhoyt]

Hmm, yeah, thanks Tony -- I think we need more thought here. The Juju docs (and as Tony shows, existing charm usage) is definitely not in line with @jameinel's comment. In addition to the ones Tony linked, more here: https://juju.is/docs/juju/status, "waiting" is defined as "The charm is alive and well, and is waiting for some event to occur. No human intervention required." -- nothing to do with integrations/relations.

I think it's partly the name that's confusing -- "waiting" is so nice and simple and the word does really mean "waiting for some event to occur".

I'd like to hear @tmihoc's thoughts on the docs side of things, but I've also put this as my list to discuss with the Juju team next Tuesday.

[tonyandrewmeyer]

I think it's partly the name that's confusing -- "waiting" is so nice and simple and the word does really mean "waiting for some event to occur".

💯

[benhoyt]

We need to sit down (maybe 20 minutes on a video call or in Madrid) with Ian, John, Tony, Dora, me, and come to consensus on this. It seems there's a bit of discrepancy in how the Juju team think about this and what our docs say:

• Ian's take is that Waiting is for when the charm's not ready because you (or something related) is doing a task like apt install, and Maintenance is for when the charm is working but in a degraded state, like reduced HA or performing a backup.
• John's take is that Waiting is for when the charm's not ready because it's waiting on something in a charm it's related to / integrated with, and Maintenance is for when the charm itself is doing something.
• The Juju doc comments for Waiting and Maintenance (and this PR now) reflect John's take.
• Our docs are all over the place too: https://juju.is/docs/juju/status is -- kind of -- John's take, whereas https://juju.is/docs/sdk/constructs#heading--statuses is something between Ian and John's take.
• Existing charm usage is a bit all over the place, but often more in line with Ian's take (TODO: links).

Update: I've put this on our list to discuss in Madrid.

[benhoyt]

We met today in Madrid, and the decision was to use "John's take" that Waiting is when the charm is waiting for an application it's related to, and Maintenance is when the charm is itself doing something. We'll change the wording of all places to be consistent (Juju source, Ops source / reference docs, Juju doc, Juju SDK doc -- maybe the latter can link to the Juju doc).

Something like this:

• Maintenance: set this status when the charm is performing an operation such as apt install or waiting for something under its control, such as pebble-ready or an exec operation in the workload container. In contrast to Waiting, Maintenance reflects activity on this unit or charm, not on peers or related units.
• Waiting: set this status when waiting on a charm this is integrated with. For example, a web app charm would set Waiting status when it is integrated with a database charm that is not ready yet (for example, creating a database). In contrast to Maintenance, Waiting reflects activity on related units, not on this unit or charm.

In addition, add to Active something like "If the unit or application is operational but something (like high availability) is in a degraded state, set Active with an appropriate message."

[dimaqq]

I've updated the PR title to match our conventional commit settings.

[tonyandrewmeyer]

In case it's of use, these are the docs I wrote for Scenario (before we decided to implement a copy-docstring-from-ops approach instead):

unknown:

    """The unit status is unknown.

    A unit-agent has finished calling install, config-changed, and start, but the
    charm has not called status-set yet.

    This status is read-only; trying to set unit or application status to ``UnknownStatus`` will raise
    :class:`ModelError`.
    """

error:

    """The unit status is error.

    The unit-agent has encountered an error (the application or unit requires
    human intervention in order to operate correctly).

    This status is read-only; trying to set unit or application status to ``ErrorStatus`` will raise
    :class:`ModelError`.
    """

active:

    """The unit/app is ready.

    Use the :attr:`message` to provide details when the unit/app is operational
    but in a degraded state (such as lacking high availability).
    """

blocked:

    """The unit/app requires manual intervention.

    An admin has to manually intervene to unblock the unit/app and let it proceed.
    """

maintenance:

    """The unit/app is performing maintenance tasks.

    The unit/app is performing an operation such as ``apt install`` or waiting for
    something under its control, such as ``pebble-ready`` or an ``exec``
    operation in the workload container.

    In constrast to :class:`WaitingStatus`, ``MaintenanceStatus`` reflects
    activity on this unit or charm, not on peers or related units.
    """

waiting:

    """The unit/app is waiting on an integration.

    The unit/app is waiting on a charm with which it is integrated, such as
    waiting for an integrated database charm to provide credentials.

    In contrast to :class:`MaintenanceStatus`, ``WaitingStatus`` reflects
    activity on integrated units, not on this unit or charm.
    """

[benhoyt]

I've updated this based on my comment above (which was based on our discussion in Madrid).

[tonyandrewmeyer]

LGTM!

[benhoyt]

I also made some clarifications to https://juju.is/docs/juju/status, and it looks like Dora already updated https://juju.is/docs/sdk/status. So I think we're all in sync now.