search

canonical / ops-scenario

State-transition testing SDK for Operator Framework Juju charms.
Apache License 2.0
10 stars 7 forks source link

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

Closed tonyandrewmeyer closed 2 weeks ago

tonyandrewmeyer commented 2 months ago

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).

tonyandrewmeyer commented 2 months ago

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 commented 2 months ago

@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.

tonyandrewmeyer commented 2 months ago
  1. 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'.

  1. 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).

tonyandrewmeyer commented 3 weeks ago

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.