Re: [PATCH v2 1/3] migration/doc: Add documentation for backwards compatiblity

[Peter Maydell]

On Tue, 17 Oct 2023 at 16:20, Juan Quintela <quintela@redhat.com> wrote:
>
> State what are the requeriments to get migration working between qemu
> versions.  And once there explain how one is supposed to implement a
> new feature/default value and not break migration.
>
> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
> Acked-by: Peter Xu <peterx@redhat.com>
> Signed-off-by: Juan Quintela <quintela@redhat.com>
> ---
>  docs/devel/migration.rst | 217 +++++++++++++++++++++++++++++++++++++++
>  1 file changed, 217 insertions(+)
>
> diff --git a/docs/devel/migration.rst b/docs/devel/migration.rst
> index c3e1400c0c..5ef2b36e9e 100644
> --- a/docs/devel/migration.rst
> +++ b/docs/devel/migration.rst
> @@ -142,6 +142,223 @@ General advice for device developers
>    may be different on the destination.  This can result in the
>    device state being loaded into the wrong device.
>
> +How backwards compatibility works
> +---------------------------------

Is there a better place in this document that we could add
this information? At the moment these new sections have
been placed in the middle of the "Saving the state of one device"
section, which doesn't seem right; worse, it's between the
"General advice for device developers" and the "VMState"
subsections of that section, which means that we end up with
a very long part of the document that is talking about edge
cases, and which splits up the two parts of the document that
are really all most device model authors need to think about.

My guess is that the extra documentation on backwards
compatibility that these patches are adding should get
a new section of its own (at the same level as the current
top-level sections "Transports", "Debugging", etc) which
then has its own subsections; and that this should probably
go either at the bottom of the document, after "Firmware",
or else just before "Stream structure".

We should probably also add a
.. contents::
directive near the start of the page, since it's now big
enough and has enough sections and subsections that a
table of contents would be helpful.

thanks
-- PMM