Re: [libvirt] [RFC] Toward a better NEWS file
On Wed, 2016-10-19 at 15:19 +0200, Martin Kletzander wrote:
> > Why don't we simply have a NEWS file in GIT, and
require that
> > non-trivial commits or patch series include an update to NEWS,
> > so the NEWS file gets populated at time the feature/bug fix
> > gets merged.
>
> I'm strongly against adding more generated files to the
> repository; if anything, we should have *less* of them[1].
>
> But if we required the source file, docs/news.html.in, to
> be updated along with notable changes instead, I would be
> all for it! :)
I understood it like this:
- stop generating NEWS file
- populate NEWS file with notable features/bug-fixes along with the
changes themselves
- use NEWS to make nice news.html
Why would we build news.html from NEWS when we already have
a perfectly fine way to build both NEWS and news.html from
news.html.in?
> [1] Hello, HACKING!
Yeah, that's a problem, we want the plain-text HACKING to be there, but
we want the stuff to be on the web page too. This could be fixed by
making hacking.html.in generated from HACKING and changing HACKING to
use some kind of plaint-text friendly formatted text (org, rst, md, …)
in order not to lose the metadata ;)
I was discussing this offline with Ján just yesterday.
IMHO the way forward is to basically
* stop building HACKING from hacking.html.in
* move README-hacking to HACKING
* (optionally) rename hacking.html.in to
contributorguidelines.html.in - that's already the title
of the document anyway
* improve the contents of both HACKING and hacking.html.in
I think HACKING should contain just the information required
to get from a fresh git clone to a buildable source tree, eg.
the extra steps you wouldn't have to take if you were building
from a release archive. And README-hacking is basically there
already.
--
Andrea Bolognani / Red Hat / Virtualization