docs: add instructions for moving from 6.x to 7.x

[tonyandrewmeyer]

Since 7.x has so many breaking changes, add an UPGRADING.md doc that lists them all, with before/after examples.

Note that this is not the full release notes for 7.x - it doesn't cover any of the non-breaking changes, other than when they are incidentally used as part of the examples. We can write release notes for the release fairly shortly, which can be more comprehensive (but probably not have as many examples).

[dimaqq]

Maybe it's a good idea to add a change log to this repo 🤔

[tonyandrewmeyer]

Maybe it's a good idea to add a change log to this repo 🤔

I think this partly depends on where we end up landing with 'officialising' Scenario. If you're always expected to get it with pip install ops[testing] and that gets you a specific version of what's currently in ops-scenario, then possibly the changes belong in a section in the operator repo's changelog. If not, then I think so, yes, especially since the release process is automated so the release notes are minimal.

[tonyandrewmeyer]

@tmihoc there will likely be a few more changes to be added before we release 7.x, but if you have time would you mind having a look over this in terms of the general structure and so on?

I think when we release we would also probably add a Discourse post that has roughly the same content.

[tmihoc]

1. The content looks pretty good but I think it can be streamlined further, by making the titles all follow a similar pattern of "what's true now" and the sections all follow the same pattern of before - now (- comments).

2. Imo this can be the actual content of the release notes (following the pattern of https://juju.is/docs/juju/roadmap#juju-juju-300-22-oct-2022 , which is not perfect but did do the job at the time, and also linked to docs giving further info).

3. How about we set up an RTD project for Scenario? Then we can publish the notes there. (And link to them from the charm SDK docs.)

[tonyandrewmeyer]

2. Imo this can be the actual content of the release notes

No objection to having this content in the release notes (as well as more info that covers the non-breaking changes). But I do think that there should be a separate file in the repo for at least the 7.x series so that it's available for anyone 'offline'.

3. How about we set up an RTD project for Scenario? Then we can publish the notes there. (And link to them from the charm SDK docs.)

The intention is that this cycle we'll integrate Scenario into ops (I'm working on a spec that figures out the details at the moment). The general plan is that you do pip install ops[testing] and you'll get Scenario installed, and the classes will be in the ops namespace, so you have code like:

from ops import testing

state = testing.State(...)

So I think part of this should be that the docs appear where the ops ones do as well - so another item in the menu on ops.rtd for reference docs, and the other 3 quadrants are wherever the ops ones are as well. Basically, Scenario will just be another component of ops, so the docs should match that (and the "Scenario" name is unfortunately going away, because it's being reserved for a different project at Canonical).

[benhoyt]

Nice! A few minor comments from me.

[benhoyt]

I still have to look at the 6.0 vs 7.0 API reference side by side, but this doc looks really good, thanks!

[tonyandrewmeyer]

Note for me: some fool has written "dictionaryes" in there. I can't even fathom typing this, but I suppose it must have happened 😆. I should run a quick spell check over it.

[tmihoc]

I've only looked at the UPGRADING.md file (as the rest seems to be build stuff).

Regarding the latest changes: I only had a nipick -- feel free to ignore.

Regarding the doc overall, my thoughts are as before:

• The content looks pretty good but I think it can be streamlined further, by making the titles all follow a similar pattern of "what's true now in 7.x" and the sections all follow the same pattern of before - now (- comments). E.g., instead of "Specify events via context.on", have "Events must be specified via context.on". (The "Specify.. title" gives off a how-to guide vibe, which is not completely unjustified, but feels like it has the wrong focus. The purpose of the doc is not just to tell people how to upgrade to 7.x but also to inform them of what 7.x is like -- and the latter bit is in a way the only indispensable bit (the how-to bit can be deduced from it and the why is nice but in a way optional), so it must dictate the perspective.
• Imo this can be the actual content of the release notes (following the pattern of https://juju.is/docs/juju/roadmap#juju-juju-300-22-oct-2022 , which is not perfect but did do the job at the time, and also linked to docs giving further info -- which we should do as well once we've digested what the incorporation of scenario into ops means for what we recommend for testing).

[dimaqq]

I wonder if these settings should be in the repo or developer's own checkout.

[tonyandrewmeyer]

Ah, I missed that I had added this file 😄. They are ones that are somewhat specific to this project (which is why I added them to the project workspace and not the global one). But having the .vscode folder in .gitignore also seems reasonable to me.