[Qemu-devel] [PATCH v2 0/2] docs/interop/bitmaps: rewrite and modernize doc

John Snow posted 2 patches 4 years, 11 months ago
Test checkpatch passed
Test asan passed
Test docker-clang@ubuntu passed
Test docker-mingw@fedora passed
Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/qemu tags/patchew/20190422221714.7630-1-jsnow@redhat.com
Maintainers: John Snow <jsnow@redhat.com>, Fam Zheng <fam@euphon.net>
There is a newer version of this series
docs/interop/bitmaps.rst | 1600 ++++++++++++++++++++++++++++++--------
Makefile                 |    2 +-
2 files changed, 1266 insertions(+), 336 deletions(-)
[Qemu-devel] [PATCH v2 0/2] docs/interop/bitmaps: rewrite and modernize doc
Posted by John Snow 4 years, 11 months ago
The documentation as written in the 4.0 release is not quite correct as
of the 4.0 release; though thanks to backwards compatibility it's not
quite wrong either. It is suitable for inclusion in 4.0.1, or any
downstream that packages 4.0.

This patch is an attempt at a nearly full rewrite that revitalizes this
document to address frequent questions I encounter when discussing the
API.

V2:
  - Split off makefile change into its own little patch.

  - Addressed (almost) all comments from Vladimir.
    - Example styling was not reworked.
  - Renamed all filenames to be consistent throughout the document,
    fixing a few more file extensions in the process
  - Reflowed almost all paragraphs to 78 columns for consistency.
  - Changed a few bulleted lists to paragraphs instead
  - Changed the big ascii text diagram to a more compact version
    and clarified its language
  - While in general I prefer to use en_US spellings, I have
    replaced "canceled" with "cancelled" so it does not look
    out of place juxtaposed with BLOCK_JOB_CANCELLED...

Future work that remains to be done:

- Paying heed to blockdev-backup workflows
- Adding a small migration section explaining the options there
- Possibly reworking some of the sections that all make their own
  repeated attempts to clarify time interval discretization and adding
  a proper treatment of the idea start to finish; this may be neccessary
  to explain the two below items properly:
- Differential Backups
- Pull Backups and NBD

John Snow (2):
  Makefile: add nit-picky mode to sphinx-build
  docs/interop/bitmaps: rewrite and modernize doc

 docs/interop/bitmaps.rst | 1600 ++++++++++++++++++++++++++++++--------
 Makefile                 |    2 +-
 2 files changed, 1266 insertions(+), 336 deletions(-)

-- 
2.20.1


Re: [Qemu-devel] [PATCH v2 0/2] docs/interop/bitmaps: rewrite and modernize doc
Posted by Vladimir Sementsov-Ogievskiy 4 years, 11 months ago
23.04.2019 1:17, John Snow wrote:
> The documentation as written in the 4.0 release is not quite correct as
> of the 4.0 release; though thanks to backwards compatibility it's not
> quite wrong either. It is suitable for inclusion in 4.0.1, or any
> downstream that packages 4.0.
> 
> This patch is an attempt at a nearly full rewrite that revitalizes this
> document to address frequent questions I encounter when discussing the
> API.
> 
> V2:
>    - Split off makefile change into its own little patch.
> 
>    - Addressed (almost) all comments from Vladimir.
>      - Example styling was not reworked.
>    - Renamed all filenames to be consistent throughout the document,
>      fixing a few more file extensions in the process
>    - Reflowed almost all paragraphs to 78 columns for consistency.
>    - Changed a few bulleted lists to paragraphs instead
>    - Changed the big ascii text diagram to a more compact version
>      and clarified its language
>    - While in general I prefer to use en_US spellings, I have
>      replaced "canceled" with "cancelled" so it does not look
>      out of place juxtaposed with BLOCK_JOB_CANCELLED...
> 
> Future work that remains to be done:
> 
> - Paying heed to blockdev-backup workflows
> - Adding a small migration section explaining the options there
> - Possibly reworking some of the sections that all make their own
>    repeated attempts to clarify time interval discretization and adding
>    a proper treatment of the idea start to finish; this may be neccessary
>    to explain the two below items properly:
> - Differential Backups
> - Pull Backups and NBD

This all looks a bit more than just "bitmaps.rst". I think at least most of things
about backups should be separated into backup.rst. (But, please, as a follow-up, if
you agree).

> 
> John Snow (2):
>    Makefile: add nit-picky mode to sphinx-build
>    docs/interop/bitmaps: rewrite and modernize doc
> 
>   docs/interop/bitmaps.rst | 1600 ++++++++++++++++++++++++++++++--------
>   Makefile                 |    2 +-
>   2 files changed, 1266 insertions(+), 336 deletions(-)
> 


-- 
Best regards,
Vladimir
Re: [Qemu-devel] [PATCH v2 0/2] docs/interop/bitmaps: rewrite and modernize doc
Posted by John Snow 4 years, 11 months ago

On 4/23/19 2:10 PM, Vladimir Sementsov-Ogievskiy wrote:
> 23.04.2019 1:17, John Snow wrote:
>> The documentation as written in the 4.0 release is not quite correct as
>> of the 4.0 release; though thanks to backwards compatibility it's not
>> quite wrong either. It is suitable for inclusion in 4.0.1, or any
>> downstream that packages 4.0.
>>
>> This patch is an attempt at a nearly full rewrite that revitalizes this
>> document to address frequent questions I encounter when discussing the
>> API.
>>
>> V2:
>>    - Split off makefile change into its own little patch.
>>
>>    - Addressed (almost) all comments from Vladimir.
>>      - Example styling was not reworked.
>>    - Renamed all filenames to be consistent throughout the document,
>>      fixing a few more file extensions in the process
>>    - Reflowed almost all paragraphs to 78 columns for consistency.
>>    - Changed a few bulleted lists to paragraphs instead
>>    - Changed the big ascii text diagram to a more compact version
>>      and clarified its language
>>    - While in general I prefer to use en_US spellings, I have
>>      replaced "canceled" with "cancelled" so it does not look
>>      out of place juxtaposed with BLOCK_JOB_CANCELLED...
>>
>> Future work that remains to be done:
>>
>> - Paying heed to blockdev-backup workflows
>> - Adding a small migration section explaining the options there
>> - Possibly reworking some of the sections that all make their own
>>    repeated attempts to clarify time interval discretization and adding
>>    a proper treatment of the idea start to finish; this may be neccessary
>>    to explain the two below items properly:
>> - Differential Backups
>> - Pull Backups and NBD
> 
> This all looks a bit more than just "bitmaps.rst". I think at least most of things
> about backups should be separated into backup.rst. (But, please, as a follow-up, if
> you agree).
> 

Yeah, it could certainly be refactored a bit, but the core goal was
"bitmap objects, and the ways you can use them."

It has obviously grown a bit since then, but the push and pull backup
relating parts could go in their own document, maybe.

I'll worry about it later.

Thanks for your help with the reviews!