WIP: Terms documentation

[AdamIsrael]

This is the first draft of documentation of the new terms functionality in juju 2.0.

[alesstimec]

juju list-agreements show user's agreements

[alesstimec]

charm terms lists terms owned by the user.. or so the doc says..

[alesstimec]

"charm show $charmURL terms" will show terms required by a charm

[alesstimec]

A few comments from me..

[mattyw]

s/Terms/terms

[mattyw]

I'd recommend giving them a subject to use, that way we can add filters to catch these messages, also maybe we should ask them to fill out a form so they don't need to send their terms to the whole list

[mattyw]

I guess I'm basically saying - let's agree a process then document it

[AdamIsrael]

I completely agree. Since your team (I think?) will be the one responsible for creating terms, how do you want to go about it? A Google spreadsheet/form seems handy in this case, but I don't know if it can be setup to send notifications when new forms are submitted.

I still favor the idea of using a Github repo, though, where the issues template can be customized for the information need. Notifications work, issues can be assigned and progress tracked.

[cmars]

Let's use a Google Form for this purpose: https://goo.gl/forms/7cGy0Oztmd

It collects all the form submissions to a spreadsheet, and I've enabled email notifications for it.

[mattyw]

I think this needs a revision @cmars ?

[alesstimec]

no.. without revision it will require agreement to the latest revision of that term

[mattyw]

@cmars is this right?

[alesstimec]

@mattyw yes, yes, it is :)

[cmars]

@AdamIsrael We've just released the fix for this to production. cs:~cmars/trusty/canonical-terms-example has a metadata.yaml requiring agreement to latest terms.

[evilnick]

when you are happy with the peer-review on any PR, if you just make a comment @juju/docs we can scan it over and merge.

[alesstimec]

@cmars i think the wording here is a bit awkward.. charm is not running under terms.. term agreement record is kept in the terms service.. so should the updates charm require newer version of terms or additional term agreement then juju upgrade-charm will ask for additional agreements.. but my english is not good enough to put this in proper sentences.

[cmars]

Let me see what I can come up with... how about:

Services run under an agreement to the terms applicable to the charm when it was deployed. When upgrading a service with juju upgrade-charm, the user may be prompted to agree to newer revisions of terms already agreed to, or to new terms that have been added to the upgrade charm revision.

[cmars]

I would like to see some improvements from @AdamIsrael per comments above in follow-ups, but I think this is a great start and from a technical perspective is good to land as-is.

LGTM.

[evilnick]

ok, cool. words look fine. Thanks 🍰

[AdamIsrael]

Thanks for the feedback, @cmars, @mattyw, and @alesstimec. I'll iterate on the docs on soon as time permits.