Thierry Carrez wrote:
Paul de Vrieze wrote:
Oh god help. This also points to another reason why this is not such a
good idea. Writing guideXML is a lot more work than writing an e-mail
format file (ciaran's proposed format for those who didn't recognize it).
Also having double files containing the same information is broken by
design.
OK so there is two options :
1- every "news" requires a GuideXML/RST/whatever errata at a central web
location
Pros:
- non-portage user can easily browse errata
- consistency in documentation
Cons:
- work overhead for errata-writing dev
2- every "news" requires just a short text-based item, extra doc is optional
Pros:
- flexibility: short news don't require writing extra doc
- external doc reuse: the documentation referenced in the news item can
be some upstream upgrade doc when sufficient
Cons:
- lack of consistency and difficulty for non-portage users to browse
I don't understand the last point really ... You can always transform
the plain text message into GuideXML (you just might not have all the
fancy markup, but even that could be solved).
So all in all I really don't understand this whole subthread, I'll just
post how I see it right now:
There will be one location (either in the tree or replicated to the
tree) which contains summary style notices for important tree updates.
The format of the notices should be as simple as possible (I've learned
this the hard way with the GLSA system) while allowing at least basic
filtering rules, I think the format described in the GLEP is good for
that. It should also be possible to easily transform those notices into
a website (be it errata.g.o or something else) that matches the general
look and feel of the Gentoo websites, should be simple enough with the
given format (but then I don't know much about XSLT).
If a notice needs a more detailed explanation that should be submitted
in the docs section (maybe a special "Upgrade Guides" section?) and
linked to from the notice.
Should also be simple enough to replicate notices to thw www.g.o
frontpage/GWN/-announce/...
Just to make this crystal clear again: The main point of the notices is
to get peoples attention so they become aware that some upgrade might
not be as smooth as usual, not necessarily to provide them with all
potential information, that's the job of the (external) upgrade guides.
One thing I'd be interested in before adding support for this: How many
such notices do people here expect per year? Mainly trying to get an
idea how this would affect the tree size and if it needs some
"housekeeping" (e.g. five files per month aren't an issue, 500 files per
month might be).
Marius
--
gentoo-dev@gentoo.org mailing list
