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

[Juan Quintela <quintela@redhat.com>]

Peter Maydell <peter.maydell@linaro.org> wrote:
> 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.

You are right.  I didn't know for a good place either.
I created a new section:

Backwards compatibility

At the end of the archive.

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

End it is.

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

Also done.

Thanks a lot.