From: Peter Xu <peterx@redhat.com>

Migration docs grow larger and larger.  There are plenty of things we can
do here in the future, but to start that we'd better reorganize the current
bloated doc files first and properly organize them into separate files.
This series kicks that off.

This series mostly does the movement only, so please don't be scared of the
slightly large diff.  I did touch up things here and there, but I didn't
yet started writting much.  One thing I did is I converted virtio.txt to
rST, but that's trivial and no real content I touched.

I am copying both virtio and vfio people because I'm merging the two
separate files into the new docs/devel/migration/ folder.

Comments welcomed.  Thanks,

Peter Xu (10):
  docs/migration: Create migration/ directory
  docs/migration: Create index page
  docs/migration: Convert virtio.txt into rST
  docs/migration: Split "Backwards compatibility" separately
  docs/migration: Split "Debugging" and "Firmware"
  docs/migration: Split "Postcopy"
  docs/migration: Split "dirty limit"
  docs/migration: Organize "Postcopy" page
  docs/migration: Further move vfio to be feature of migration
  docs/migration: Further move virtio to be feature of migration

 docs/devel/index-internals.rst                |    3 +-
 docs/devel/migration.rst                      | 1514 -----------------
 docs/devel/migration/best-practises.rst       |   48 +
 docs/devel/migration/compatibility.rst        |  517 ++++++
 docs/devel/migration/dirty-limit.rst          |   71 +
 docs/devel/migration/features.rst             |   12 +
 docs/devel/migration/index.rst                |   13 +
 docs/devel/migration/main.rst                 |  575 +++++++
 docs/devel/migration/postcopy.rst             |  313 ++++
 .../vfio.rst}                                 |    2 +-
 docs/devel/migration/virtio.rst               |  115 ++
 docs/devel/virtio-migration.txt               |  108 --
 12 files changed, 1666 insertions(+), 1625 deletions(-)
 delete mode 100644 docs/devel/migration.rst
 create mode 100644 docs/devel/migration/best-practises.rst
 create mode 100644 docs/devel/migration/compatibility.rst
 create mode 100644 docs/devel/migration/dirty-limit.rst
 create mode 100644 docs/devel/migration/features.rst
 create mode 100644 docs/devel/migration/index.rst
 create mode 100644 docs/devel/migration/main.rst
 create mode 100644 docs/devel/migration/postcopy.rst
 rename docs/devel/{vfio-migration.rst => migration/vfio.rst} (99%)
 create mode 100644 docs/devel/migration/virtio.rst
 delete mode 100644 docs/devel/virtio-migration.txt

-- 
2.41.0

On Tue, Jan 09, 2024 at 02:46:18PM +0800, peterx@redhat.com wrote:
> From: Peter Xu <peterx@redhat.com>
> 
> Migration docs grow larger and larger.  There are plenty of things we can
> do here in the future, but to start that we'd better reorganize the current
> bloated doc files first and properly organize them into separate files.
> This series kicks that off.
> 
> This series mostly does the movement only, so please don't be scared of the
> slightly large diff.  I did touch up things here and there, but I didn't
> yet started writting much.  One thing I did is I converted virtio.txt to
> rST, but that's trivial and no real content I touched.
> 
> I am copying both virtio and vfio people because I'm merging the two
> separate files into the new docs/devel/migration/ folder.

Firstly.. thanks Cedric for the super fast review.

A few things I'd like to mention alongside, because it's documentation
relevant too, and I'd like to collect if there's any comment.

I just mostly rewrote two wiki pages completely:

  https://wiki.qemu.org/ToDo/LiveMigration
  https://wiki.qemu.org/Features/Migration

I merged all the TODO items from Features/Migration into the ToDo page,
while kept the 2nd page mostly clean, just to route to other places.

I had a plan to make:

  https://qemu.org/docs/master

The solo place for migration documentations (aka, QEMU repo the source of
truth for migration docs, as it's peroidically built there), making all the
rest places pointing to that, as I already did in the wiki page.  While I
kept all the TODOs on the wiki page (not Features/Migration, but
ToDo/LiveMigration).

Fabiano / anyone: feel free to add / update / correct any entries there
where applicable.  Also if there's any thoughts on above feel free to let
me know too.

Thanks,

-- 
Peter Xu

> A few things I'd like to mention alongside, because it's documentation
> relevant too, and I'd like to collect if there's any comment.
> 
> I just mostly rewrote two wiki pages completely:
> 
>    https://wiki.qemu.org/ToDo/LiveMigration
>    https://wiki.qemu.org/Features/Migration>
> I merged all the TODO items from Features/Migration into the ToDo page,
> while kept the 2nd page mostly clean, just to route to other places.
> 
> I had a plan to make:
> 
>    https://qemu.org/docs/master
> 
> The solo place for migration documentations (aka, QEMU repo the source of
> truth for migration docs, as it's peroidically built there), making all the
> rest places pointing to that, as I already did in the wiki page.  While I
> kept all the TODOs on the wiki page (not Features/Migration, but
> ToDo/LiveMigration).> 
> Fabiano / anyone: feel free to add / update / correct any entries there
> where applicable.  Also if there's any thoughts on above feel free to let
> me know too.

The Wiki has some limited value, the changelog for instance, but the rest
is a bag of orphan and obsolete pages doomed to bit-rot since it is slowly
being replaced by the in-tree documentation.

The info in the Features/Migration page is redundant with what we have
in-tree, a part from the CREDITS. The TODO list could be some file under :

	https://qemu.org/docs/master/devel/migration

It would be easier to find and it would keep the Wiki to a strict minimum.

Cheers,

C.

On Tue, Jan 09, 2024 at 02:21:26PM +0100, Cédric Le Goater wrote:
> 
> > A few things I'd like to mention alongside, because it's documentation
> > relevant too, and I'd like to collect if there's any comment.
> > 
> > I just mostly rewrote two wiki pages completely:
> > 
> >    https://wiki.qemu.org/ToDo/LiveMigration
> >    https://wiki.qemu.org/Features/Migration>
> > I merged all the TODO items from Features/Migration into the ToDo page,
> > while kept the 2nd page mostly clean, just to route to other places.
> > 
> > I had a plan to make:
> > 
> >    https://qemu.org/docs/master
> > 
> > The solo place for migration documentations (aka, QEMU repo the source of
> > truth for migration docs, as it's peroidically built there), making all the
> > rest places pointing to that, as I already did in the wiki page.  While I
> > kept all the TODOs on the wiki page (not Features/Migration, but
> > ToDo/LiveMigration).> Fabiano / anyone: feel free to add / update /
> > correct any entries there
> > where applicable.  Also if there's any thoughts on above feel free to let
> > me know too.
> 
> The Wiki has some limited value, the changelog for instance, but the rest
> is a bag of orphan and obsolete pages doomed to bit-rot since it is slowly
> being replaced by the in-tree documentation.
> 
> The info in the Features/Migration page is redundant with what we have
> in-tree, a part from the CREDITS. The TODO list could be some file under :
> 
> 	https://qemu.org/docs/master/devel/migration
> 
> It would be easier to find and it would keep the Wiki to a strict minimum.

Thanks for the suggestions.  I agree that we should minimize the wiki use,
especially on docs.  It'll be nice we use a solo source of truth for the
docs, always accessable via qemu.org/docs, and also makes it easier for us
to ask for docs altogether as patches when new features are merged.

I see that most of the ToDos for the other part of qemus still use the wiki
page, even though they're indeed mostly outdated just like the migration
ToDo before I updated it.

IMHO one thing that the wiki services well for ToDo is that it allows easy
& frequent updates on the projects, without the need to require a review
process like most of the patches being posted on the list.  The wiki page
still maintains a diff, and IMHO that may not even be required, as a
history record of a ToDo list may not help much in most cases.

The other issue regarding ToDo is that, some of the ToDo idea (or when
someone frequently updates with details on a project of an ongoing item)
may not be mature enough to be mentioned in an official documents. So even
if some can be considered to be put together with the qemu repo, there may
always be some that may not be suitable, then we will still need some place
for those.  I still don't know what's the ideal way to do this.

Thanks,

-- 
Peter Xu

On 1/10/24 03:37, Peter Xu wrote:
> On Tue, Jan 09, 2024 at 02:21:26PM +0100, Cédric Le Goater wrote:
>>
>>> A few things I'd like to mention alongside, because it's documentation
>>> relevant too, and I'd like to collect if there's any comment.
>>>
>>> I just mostly rewrote two wiki pages completely:
>>>
>>>     https://wiki.qemu.org/ToDo/LiveMigration
>>>     https://wiki.qemu.org/Features/Migration>
>>> I merged all the TODO items from Features/Migration into the ToDo page,
>>> while kept the 2nd page mostly clean, just to route to other places.
>>>
>>> I had a plan to make:
>>>
>>>     https://qemu.org/docs/master
>>>
>>> The solo place for migration documentations (aka, QEMU repo the source of
>>> truth for migration docs, as it's peroidically built there), making all the
>>> rest places pointing to that, as I already did in the wiki page.  While I
>>> kept all the TODOs on the wiki page (not Features/Migration, but
>>> ToDo/LiveMigration).> Fabiano / anyone: feel free to add / update /
>>> correct any entries there
>>> where applicable.  Also if there's any thoughts on above feel free to let
>>> me know too.
>>
>> The Wiki has some limited value, the changelog for instance, but the rest
>> is a bag of orphan and obsolete pages doomed to bit-rot since it is slowly
>> being replaced by the in-tree documentation.
>>
>> The info in the Features/Migration page is redundant with what we have
>> in-tree, a part from the CREDITS. The TODO list could be some file under :
>>
>> 	https://qemu.org/docs/master/devel/migration
>>
>> It would be easier to find and it would keep the Wiki to a strict minimum.
> 
> Thanks for the suggestions.  I agree that we should minimize the wiki use,
> especially on docs.  It'll be nice we use a solo source of truth for the
> docs, always accessable via qemu.org/docs, and also makes it easier for us
> to ask for docs altogether as patches when new features are merged.
> 
> I see that most of the ToDos for the other part of qemus still use the wiki
> page, even though they're indeed mostly outdated just like the migration
> ToDo before I updated it.
> 
> IMHO one thing that the wiki services well for ToDo is that it allows easy
> & frequent updates on the projects, without the need to require a review
> process like most of the patches being posted on the list.  The wiki page
> still maintains a diff, and IMHO that may not even be required, as a
> history record of a ToDo list may not help much in most cases.
> 
> The other issue regarding ToDo is that, some of the ToDo idea (or when
> someone frequently updates with details on a project of an ongoing item)
> may not be mature enough to be mentioned in an official documents. So even
> if some can be considered to be put together with the qemu repo, there may
> always be some that may not be suitable, then we will still need some place
> for those.  I still don't know what's the ideal way to do this.

OK. I see how you want to use the wiki for the TODO ideas and it makes
sense for mid/long term projects which are not mature enough to be
mentioned in the official docs. That said, I think we should mention
not supported features, incomplete modelling, etc. in the official docs,
which is a bit different than a TODO, I agree.

We also have a [feature request] label under gitlab and some issues are
tagged with it. I wonder how we can consolidate the 3 sources : wiki,
gitlab, https://www.qemu.org/docs/master/

Thanks,

C.

On Wed, Jan 10, 2024 at 04:21:12PM +0100, Cédric Le Goater wrote:
> We also have a [feature request] label under gitlab and some issues are
> tagged with it. I wonder how we can consolidate the 3 sources : wiki,
> gitlab, https://www.qemu.org/docs/master/

Thanks for mentioning the gitlab issues!  This reminded me that we used to
have Dave looking after that from time to time, but it's totally overlooked
at least by myself..  probably we need to have some time tracking it.  On
the documentation side for ToDos, it's indeed potentially doable to already
merge into gitlab issues, then we merge 3->2.  I'll think about it.

-- 
Peter Xu

On Tue, Jan 09, 2024 at 02:46:18PM +0800, peterx@redhat.com wrote:
> From: Peter Xu <peterx@redhat.com>
> 
> Migration docs grow larger and larger.  There are plenty of things we can
> do here in the future, but to start that we'd better reorganize the current
> bloated doc files first and properly organize them into separate files.
> This series kicks that off.
> 
> This series mostly does the movement only, so please don't be scared of the
> slightly large diff.  I did touch up things here and there, but I didn't
> yet started writting much.  One thing I did is I converted virtio.txt to
> rST, but that's trivial and no real content I touched.
> 
> I am copying both virtio and vfio people because I'm merging the two
> separate files into the new docs/devel/migration/ folder.

I fixed all the spelling of "practice"s in patch 5, and queued it for now
into staging.

-- 
Peter Xu