[libvirt] [RFC] Toward a better NEWS file

[Andrea Bolognani]

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