Requesting docstring clarification on semantics of planned_units()

The following things are not obvious from the docstring of the model.app.planned_units() method

• Does planned unit apply to both scaling up and scaling down changes.
• Does planned unit reflect the state of juju command line issued uptil the point in time when planned units method was invoked.

For example suppose a charm has 30 deployed units and the system administrator invokes juju scale-application <charm> 1. This will result in RelationDepartedEvents for each of the 29 departing units. Will planned_units() when invoked in all of those RelationDepartedEvents yield the result 1 or will it yield 29, then 28 and so on.

[pengale]

Planned units represents the state of the controller’s model as of the the current hook invocation.

It should reflect both scale up and scale down.

It will reflect the results of a CLI command after that command has been run, any resultant hooks have been processed and sent to the controller, and the agent has updated its local copy of the model with that in the controller. Most of the time, this is transparent to the operator who ran the CLI command – you have to do work to catch the charm in the act of updating its controller state after you run an action.

I’ll work up a PR to refactor the docs so that they reflect this.

[pengale]

Code merged. Closing issue 😃