Re: [Qemu-devel] [PATCH 2/2] Documentation: Update image format information

[Stefan Hajnoczi]

On Thu, Nov 22, 2012 at 10:08:06AM +0100, Kevin Wolf wrote:
> Am 22.11.2012 08:37, schrieb Stefan Hajnoczi:
> > On Wed, Nov 21, 2012 at 04:22:07PM +0100, Kevin Wolf wrote:
> >> Am 21.11.2012 16:14, schrieb Stefan Hajnoczi:
> >>> On Wed, Nov 21, 2012 at 02:23:57PM +0100, Kevin Wolf wrote:
> >>>>  @item qed
> >>>> -Image format with support for backing files and compact image files 
> >>>> (when your
> >>>> -filesystem or transport medium does not support holes).  Good 
> >>>> performance due
> >>>> -to less metadata than the more featureful qcow2 format, especially with
> >>>> -cache=writethrough or cache=directsync.  Consider using qcow2 which 
> >>>> will soon
> >>>> -have a similar optimization and is most actively developed.
> >>>> +Old QEMU image format. Left for compatibility.
> >>>> +
> >>>> +For new images, use qcow2 instead. You might want to consider using the
> >>>> address@hidden option to get a more QED-like behaviour.
> >>>
> >>> The first sentence should be kept, it describes the general feature set
> >>> and scope of this image format.  I agree that the rest of the paragraph
> >>> can be dropped.
> >>>
> >>> You could insert a statement saying that qcow2 is now preferred because
> >>> it is actively developed and offers advanced features and performance as
> >>> the very first sentence.
> >>
> >> It's the same terse description as for qcow1. If we decided to describe
> >> the format in more detail, we should do so consistently, and probably
> >> also for non-native formats. (But why? The only use case is
> >> compatibility with other/older hypervisors, which is mentioned.)
> > 
> > Yes, we should have descriptions of other formats too.
> > 
> > Users dealing with existing guests using these formats should still have
> > access to general information about the formats.  For example, if I'm a
> > new user and it's my job to work with an existing qcow1 disk image then
> > it's not very helpful to just see a terse "Use qcow2 instead" message.
> >
> > It's not good to drop documentation on a feature because it is
> > deprecated.
> 
> I can see your point, but the whole section starts to become a bit
> lengthy then for a man page. Also, I don't think that your qcow1 user
> really needs a detailed description - he already has a format and
> doesn't have to choose one, so the characteristics aren't that
> important. If he considers converting the image, we're back to raw and
> qcow2.
> 
> Maybe we should keep the current descriptions for raw and qcow2 (as they
> are what users really choose between for new images), and extend and
> move the documentation of other formats into qemu-doc.texi and mention
> them in the man page of qemu-img only as "Also supported for
> compatibility with other hypervisors or older QEMU versions: vmdk, vdi,
> qed, ... See the QEMU Emulator User Documentation for more information
> on these."

Sounds good.

Stefan