Re: [Qemu-block] [Qemu-devel] [PATCH v3] live-block-ops.txt: Rename, rewrite, and improve it
On 06/23/2017 04:15 AM, Kashyap Chamarthy wrote: > On Thu, Jun 22, 2017 at 10:13:03AM -0400, John Snow wrote: >> On 06/22/2017 04:56 AM, Kashyap Chamarthy wrote: >>> On Wed, Jun 21, 2017 at 06:49:02PM -0400, John Snow wrote: > > [...] > >>> Yes, I was thinking of this, too -- just link to the 'bitmaps' document. >>> >>> A quick side question here: Since upstream QEMU is converging onto >>> Sphinx, and rST, hope you mind if I convert docs/devel/bitmaps.md into >>> rST at somepoint, for consistency's sake. I'll file a separate review, >>> anyway for that. In the long term, all / most other documents would >>> also be converted. >>> >> >> Of course not. I chose bitmaps.md so that it would be nice to view from >> the github interface while remaining nice to read in plaintext, but feel >> free to convert it if we actually do standardize on Sphinx/rST. >> >> If you can make the generated output look prettier than the github >> rendering of the markdown I'll ACK it ;) > > :-) Here's a sneak-peak (don't miss the index to your left hand side): > > > https://kashyapc.fedorapeople.org/v3-QEMU-Docs/_build/html/docs/bitmaps.html > Looking good, you've got an errant backslash: 'Let’s assume the full backup is named full\_backup.img.' I also think we should change "Let’s assume it is named incremental.0.img." to "Let's assume the new incremental image is named incremental.0.img" so as to avoid "it" when dealing with two images. Otherwise, LGTM. > Compare that with the GitHub rendering: > > https://github.com/qemu/qemu/blob/master/docs/devel/bitmaps.md > > And, here's the source (in reStructuredText, despite the ".txt" > extension) for the 'bitmaps' doc (I made tiny styling changes): > > > https://kashyapc.fedorapeople.org/v3-QEMU-Docs/_build/html/_sources/docs/bitmaps.txt > >>> Yes, I fully agree with your suggestion. I will simply link to the >>> detailed document you wrote, which I was thinking of anyhow. >>> >>> Thanks for your comments! >>> >> Sure. You could perhaps mention the different sync modes, including top, >> none, full and incremental and urge readers to check out the bitmaps >> document for detailed workings of the incremental mode. > > Yeah, good point. I'll make that edit in v2. >
Re: [Qemu-block] [Qemu-devel] [PATCH v3] live-block-ops.txt: Rename, rewrite, and improve it
On Thu, Jun 22, 2017 at 10:13:03AM -0400, John Snow wrote: > On 06/22/2017 04:56 AM, Kashyap Chamarthy wrote: > > On Wed, Jun 21, 2017 at 06:49:02PM -0400, John Snow wrote: [...] > > Yes, I was thinking of this, too -- just link to the 'bitmaps' document. > > > > A quick side question here: Since upstream QEMU is converging onto > > Sphinx, and rST, hope you mind if I convert docs/devel/bitmaps.md into > > rST at somepoint, for consistency's sake. I'll file a separate review, > > anyway for that. In the long term, all / most other documents would > > also be converted. > > > > Of course not. I chose bitmaps.md so that it would be nice to view from > the github interface while remaining nice to read in plaintext, but feel > free to convert it if we actually do standardize on Sphinx/rST. > > If you can make the generated output look prettier than the github > rendering of the markdown I'll ACK it ;) :-) Here's a sneak-peak (don't miss the index to your left hand side): https://kashyapc.fedorapeople.org/v3-QEMU-Docs/_build/html/docs/bitmaps.html Compare that with the GitHub rendering: https://github.com/qemu/qemu/blob/master/docs/devel/bitmaps.md And, here's the source (in reStructuredText, despite the ".txt" extension) for the 'bitmaps' doc (I made tiny styling changes): https://kashyapc.fedorapeople.org/v3-QEMU-Docs/_build/html/_sources/docs/bitmaps.txt > > Yes, I fully agree with your suggestion. I will simply link to the > > detailed document you wrote, which I was thinking of anyhow. > > > > Thanks for your comments! > > > Sure. You could perhaps mention the different sync modes, including top, > none, full and incremental and urge readers to check out the bitmaps > document for detailed workings of the incremental mode. Yeah, good point. I'll make that edit in v2. -- /kashyap
Re: [Qemu-block] [Qemu-devel] [PATCH v3] live-block-ops.txt: Rename, rewrite, and improve it
On 06/22/2017 04:56 AM, Kashyap Chamarthy wrote: > On Wed, Jun 21, 2017 at 06:49:02PM -0400, John Snow wrote: > > [...] > >>> * TODO (after feedback from John Snow): >>>- Eric Blake suggested to consider documenting incremental backup >>> policies as part of the section: "Live disk backup --- >>> `drive-backup` and `blockdev-backup`" >> >> Perhaps it could be mentioned, but hopefully I've covered it in some >> sufficient detail in the (now) docs/devel/bitmaps.md file; > > Yes, that doc is very useful. That was my precise thought. > >> I'm a little wary of duplicating efforts in this area, > > I share your wariness. > >> but you've covered everything *else* in good detail here, so now my >> file is the odd one out. >> >> I will leave this up to you, really. Perhaps it could be paid some lip >> service with a link to the other document? > > Yes, I was thinking of this, too -- just link to the 'bitmaps' document. > > A quick side question here: Since upstream QEMU is converging onto > Sphinx, and rST, hope you mind if I convert docs/devel/bitmaps.md into > rST at somepoint, for consistency's sake. I'll file a separate review, > anyway for that. In the long term, all / most other documents would > also be converted. > Of course not. I chose bitmaps.md so that it would be nice to view from the github interface while remaining nice to read in plaintext, but feel free to convert it if we actually do standardize on Sphinx/rST. If you can make the generated output look prettier than the github rendering of the markdown I'll ACK it ;) >> The detail in bitmaps.md is a little more verbose than the rest of >> this file, so if you include it wholesale it'd dwarf the rest of this >> document. >> >> What do you think? > > Yes, I fully agree with your suggestion. I will simply link to the > detailed document you wrote, which I was thinking of anyhow. > > Thanks for your comments! > Sure. You could perhaps mention the different sync modes, including top, none, full and incremental and urge readers to check out the bitmaps document for detailed workings of the incremental mode.
Re: [Qemu-block] [Qemu-devel] [PATCH v3] live-block-ops.txt: Rename, rewrite, and improve it
On Wed, Jun 21, 2017 at 06:49:02PM -0400, John Snow wrote: [...] > > * TODO (after feedback from John Snow): > >- Eric Blake suggested to consider documenting incremental backup > > policies as part of the section: "Live disk backup --- > > `drive-backup` and `blockdev-backup`" > > Perhaps it could be mentioned, but hopefully I've covered it in some > sufficient detail in the (now) docs/devel/bitmaps.md file; Yes, that doc is very useful. That was my precise thought. > I'm a little wary of duplicating efforts in this area, I share your wariness. > but you've covered everything *else* in good detail here, so now my > file is the odd one out. > > I will leave this up to you, really. Perhaps it could be paid some lip > service with a link to the other document? Yes, I was thinking of this, too -- just link to the 'bitmaps' document. A quick side question here: Since upstream QEMU is converging onto Sphinx, and rST, hope you mind if I convert docs/devel/bitmaps.md into rST at somepoint, for consistency's sake. I'll file a separate review, anyway for that. In the long term, all / most other documents would also be converted. > The detail in bitmaps.md is a little more verbose than the rest of > this file, so if you include it wholesale it'd dwarf the rest of this > document. > > What do you think? Yes, I fully agree with your suggestion. I will simply link to the detailed document you wrote, which I was thinking of anyhow. Thanks for your comments! -- /kashyap
Re: [Qemu-block] [Qemu-devel] [PATCH v3] live-block-ops.txt: Rename, rewrite, and improve it
On 06/21/2017 06:19 AM, Kashyap Chamarthy wrote:
> This edition documents (including their QMP invocations) all four
> operations:
>
> - `block-stream`
> - `block-commit`
> - `drive-mirror` (& `blockdev-mirror`)
> - `drive-backup` (& `blockdev-backup`)
>
> Things considered while writing this document:
>
> - Use reStructuredText as markup language (with the goal of generating
> the HTML output using the Sphinx Documentation Generator). It is
> gentler on the eye, and can be trivially converted to different
> formats. (Another reason: upstream QEMU is considering to switch to
> Sphinx, which uses reStructuredText as its markup language.)
>
> - Raw QMP JSON output vs. 'qmp-shell'. I debated with myself whether
> to only show raw QMP JSON output (as that is the canonical
> representation), or use 'qmp-shell', which takes key-value pairs. I
> settled on the approach of: for the first occurence of a command,
> use raw JSON; for subsequent occurences, use 'qmp-shell', with an
> occasional exception.
>
> - Usage of `-blockdev` command-line.
>
> - Usage of 'node-name' vs. file path to refer to disks. While we have
> `blockdev-{mirror, backup}` as 'node-name'-alternatives for
> `drive-{mirror, backup}`, the `block-commit` command still operate
> on file names for parameters 'base' and 'top'. So I added a caveat
> at the beginning to that effect.
>
> Refer this related thread that I started (where I learnt
> `block-stream` was recently reworked to accept 'node-name' for 'top'
> and 'base' parameters):
> https://lists.nongnu.org/archive/html/qemu-devel/2017-05/msg06466.html
> "[RFC] Making 'block-stream', and 'block-commit' accept node-name"
>
> All commands showed in this document were tested while documenting.
>
> Thanks: Eric Blake for the section: "A note on points-in-time vs file
> names". This useful bit was originally articulated by Eric in his
> KVMForum 2015 presentation, so I included that specific bit in this
> document.
>
> Signed-off-by: Kashyap Chamarthy
> ---
> * A Sphinx-rendered HTML version is here:
>
> https://kashyapc.fedorapeople.org/v3-QEMU-Docs/_build/html/docs/live-block-operations.html
>
>
[snip]
>
> * TODO (after feedback from John Snow):
>- Eric Blake suggested to consider documenting incremental backup
> policies as part of the section: "Live disk backup ---
> `drive-backup` and `blockdev-backup`"
Perhaps it could be mentioned, but hopefully I've covered it in some
sufficient detail in the (now) docs/devel/bitmaps.md file; I'm a little
wary of duplicating efforts in this area, but you've covered everything
*else* in good detail here, so now my file is the odd one out.
I will leave this up to you, really. Perhaps it could be paid some lip
service with a link to the other document? The detail in bitmaps.md is a
little more verbose than the rest of this file, so if you include it
wholesale it'd dwarf the rest of this document.
What do you think?
