Re: [libvirt] [PATCH] news: Make changes understandable for users
On Tue, 2017-03-28 at 22:17 +0200, Martin Kletzander wrote:
> This one looks like it would qualify on several accounts,
> but it could also definitely use a description to flesh out
> exactly what was changed, something along the lines of
>
> <summary>
> Initialize volumes properly when building LVM storage pools
> </summary>
> <description>
> Volumes containing filesystem signatures need to have it
> wiped out before they can be used in an LVM storage pools.
> libvirt was unable to wipe out the signature for some
> filesystem (such as ext4) but that limitation has now been
> addressed.
> </description>
Yeah, that's almost perfect (s/an LVM/LVM/), but I understand that not
everyone wants to come up with such description. It would not have to
be if it was similarly worded in the commit message.
I'll be honest: it took me several passes (and several
minutes) to come up with that text, so I can see quite
clearly how not everyone would be willing to spend the
same amount of time and effort on release notes.
Anyway, I guess I'm just overreacting to some of these
changes. I'm
sorry for that. I just feel like we went out of our ways to make
something nicer for the users out there, and start falling back into the
old tracks not long after it. I compare it to git's release notes [1]
which I always find a) very understandable and b) to the point
(i.e. brief, no fuzzing around, but also missing only information you
can easily find out yourself, e.g. in a man page), but I don't know why
I'm so touchy regarding this subject.
Git's release notes have clearly been written and edited
by a single individual, so of course they're going to be
more consistent in tone and style than whatever our fairly
large community of contributors can come up with over the
span of a release.
My original intention was to be more active on this front
and provide more oversight, including editing entries
outright if necessary. I have unfortunately failed to do
a very good job so far, and I apologize for that.
But I wouldn't say all hope is lost: for starters, I'll
try to find some time to improve the release notes for
the current release before the end of the freeze. And
since you seem to be taking interest in the issue, maybe
we can both try to work on it on an ongoing basis? :)
--
Andrea Bolognani / Red Hat / Virtualization