Re: [gentoo-dev] GLEP ??: Critical News Reporting

[John Myers]

[[ACK! I sent this out from the wrong address before. Hope you don't get it 
twice!]]
On Thursday 03 November 2005 21:44, Nathan L. Adams wrote:
> No, I happen to understand the that point. Emerge outputting a short
> summary is great. But the GLEP should cover the "hey mr. end user, the
> central repository for errata/full fledged migration guides is here:
> [insert url]" as well.
[snip]
> I happen to think that the assumption that the errata are going to be
> small is a bad one. I think if errata is neccessary in the first place
> then its going to be something larger than a screen's worth of console
> output and worth the supposed trouble of GuideXML. So why not approach
> it from the GuideXML end first, and extract the summary from that?
Here's an idea for a compromise solution. Sorry it's so messy:

The errata entries would consist of two files per language:
- An emerge news file, identical to the format ciaranm proposed.
    This file would give a very general notice of the issue, such as that 
    given as an example in the GLEP, as well as containing the 
    machine-readable commands for portage to control display.
  This file's name would end in .news.<LC>.txt
- A GuideXML-formatted errata document.
    This would be the actual migration guide, such as the contents of the
         http://www.gentoo.org/doc/en/yoursql-upgrading.xml
    referenced by the example.
  This file's name would end in .guide.<LC>.xml
- The leading part of the filename would be as in ciaranm's GLEP

Once it is time for the errata item to be published (after review, etc.), the 
files would be placed in a standard location, where an automated process 
would pick them up. The news files would be transferred to the Portage tree 
for emerge to pick up, and simultaneously published to a central errata 
website, e.g. http://errata.gentoo.org/. On the errata website, *all* errata 
notices would be published to its front page, unless specified differently by 
each individual user (perhaps a feature storing filters in a cookie). Each 
entry in the list would contain at least the publication date, the title of 
the news item as a link to a news item page, and the title of the guideXML 
document as a link to the document. 

Errata items would be accessible in a uniform namespace with names derived 
from their source filenames. For example:
    2005-11/2005-11-01-mysql-4.0-4.1-upgrade.news.en.txt
    2005-11/2005-11-01-mysql-4.0-4.1-upgrade.guide.en.xml
might become:
    http://errata.gentoo.org/2005-11-01-mysql-4.0-4.1-upgrade/en/
    http://errata.gentoo.org/2005-11-01-mysql-4.0-4.1-upgrade/en/guide.xml
    
For user convenience, URLs with language codes the text is not yet translated 
to, as well as URLs without a language code, should be redirected to the 
English version.

Errata items may be published in other areas for wider exposure, but should 
always contain a link back to the main source.

The news item page would contain a copy of the news text typeset in a 
fixed-width font, and with links made clickable, as well as a prominent link 
to the GuideXML document. The title of the page should be the title of the 
news item, and the title of the link to the GuideXML page should be the title 
of the GuideXML document.

Questions? Comments?