Code review comment for lp:~hazmat/pyjuju/formula-upgrades-spec

[1]

+Formula Upgrades
+----------------

Our sections have been using mixed casing in the documentation.
In user-oriented-docs I did a full round to clean that up and
make them "Title case".

Please change this to "Formula upgrades" and the other sections
accordingly.

[2]

+A common task when doing formula development, is iterating over
(...)
+In some cases a new formula version, will also reference newer

Please drop the comma in both sentences. In both cases it's
separating the subject from the predicate.

I promise not to bother too much about that kind of issue. It's just
that this specific misuse feels specially weird when reading because
it puts a sentence "pause" in an awkward location.

[3]

+In some cases a new formula version, will also reference newer
+software/package versions or new package versions.

package versions or package versions..

I guess you intended to say new packages or new package versions?

[4]

+formula upgrades as an immediately useful and required use case for
+the purpose.

Please drop or complement "for the purpose" (for the purpose of ...).

[5]

This document should really be split in two: one which talks about
the way in which Ensemble sees upgrades in several areas, and another
which talks about formula upgrades more specifically.

Put the following sections on the generic one:

+Upgrades (the global header + comment)
(...)
+Service Upgrades
(...)
+Formula Upgrades
(...)
+Ensemble Upgrades

Then, put the following one in the formula-specific document:

+Upgrading A Formula

Split this latter document into two parts:

1) User-oriented management of formula upgrading through the UI
2) Writing a formula which is ready for being upgraded

The second one may actually have a better home as a section of the
existent formula documentation in the future, but let's have it
as an external document just for the sake of debating about it in
isolation.

[6]

+ $ ensemble upgrade-formula <service-name>

Can we name this as simply "upgrade"? We don't have deploy-formula,
and it's even more confusing given that the argument after upgrade is
a service name, not a formula name.

[7]

+Which will examine the named service, determine its formula, check
the
+formula's originating repository for a newer version of the formula.
+If a newer formula version is found, it will be uploaded to the
ensemble
+environment, and downloaded to all the running units of the service.

This single sentence is pretty much the whole *actual* specification. :-)

This sentence feels good for a high-level introductory description,
but the specification needs to go into more detail about these phases,
with some content probably moved into an "Internals" section.

E.g. How's a newer version of a formula defined like? What if the
versions conflict (the case brought up by Clint)? What does it mean
to "upload to the environment", and who does it? How will the unit
agent know it has to download a new formula? How does the replacement
take place? What if there are established relations? What if there
was previously existent data in the directory? And so on.