[libvirt] [RFC] Toward a better NEWS file

[Andrea Bolognani]

On Wed, 2016-10-19 at 21:40 +0200, Martin Kletzander wrote:
> > > 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?
> 
> I meant news.html.in of course.  But we can be updating news.html.in and
> keep all the files generated as they are now.

My point is that it's generally easier to generate
an unstructured file (NEWS) from a structured source
(news.html.in) than going the other way around.

Of course we could switch the NEWS file to Markdown or
something like that, but then our build process would require
yet one more tool.

I'm also not sure all of us are as proficient with these
pseduo-markup languages as we are with HTML, which is already
fairly heavily used in our documentation: speaking just for
myself, of the formats you proposed below, I could do
Markdown, but ReStructured Text is something that I would
have to learn from scratch just to edit this one file, and
I don't even know what "org" is :D

> > > > [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.
> 
> OK, so you had different plans while I was just thinking how to keep the
> same things in place but remove redundant duplicates from git.

I had patches that got rid of the duplicated content in git
as far back as a year ago[1], but at the time there was some
very reasonable pushback because we still want to provide
some direction to people who just cloned the git repository.

The proposal above solves all the issues I have with the
HACKING file while taking care of the original concerns as
well, so I'm quite happy with it :)


[1] https://www.redhat.com/archives/libvir-list/2015-October/msg00740.html
-- 
Andrea Bolognani / Red Hat / Virtualization