docs/interop/bitmaps.rst | 1600 ++++++++++++++++++++++++++++++-------- Makefile | 2 +- 2 files changed, 1266 insertions(+), 336 deletions(-)
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
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
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!
© 2016 - 2024 Red Hat, Inc.