--- xml/htdocs/proj/en/glep/glep-0042.html 2006/03/06 03:12:58 1.11 +++ xml/htdocs/proj/en/glep/glep-0042.html 2006/06/12 22:03:32 1.12 @@ -15,8 +15,8 @@ /* :Author: David Goodger :Contact: goodger@users.sourceforge.net -:date: $Date: 2006/03/06 03:12:58 $ -:version: $Revision: 1.11 $ +:date: $Date: 2006/06/12 22:03:32 $ +:version: $Revision: 1.12 $ :copyright: This stylesheet has been placed in the public domain. Default cascading style sheet for the PEP HTML output of Docutils. @@ -275,11 +275,11 @@ Title:Critical News Reporting -Version:1.9 +Version:1.10 Author:Ciaran McCreesh <ciaranm at gentoo.org> -Last-Modified:2006/03/06 03:12:08 +Last-Modified:2006/06/12 22:03:07 Status:Draft @@ -289,7 +289,7 @@ Created:31-Oct-2005 -Post-History:1-Nov-2005, 5-Nov-2005, 7-Nov-2005, 11-Dec-2005, 13-Dec-2005, 18-Dec-2005, 5-Jan-2006, 2-Mar-2006, 6-Mar-2006 +Post-History:1-Nov-2005, 5-Nov-2005, 7-Nov-2005, 11-Dec-2005, 13-Dec-2005, 18-Dec-2005, 5-Jan-2006, 2-Mar-2006, 6-Mar-2006, 12-Jun-2006 @@ -297,46 +297,46 @@

Contents

-

Abstract

+

Abstract

This GLEP proposes a new way of informing users about important updates and news related to the tree.

-

Motivation

+

Motivation

Although most package updates are clean and require little user action, occasionally an upgrade requires user intervention. Recent examples of the latter include the gcc-3.4 stabilisation on x86 and the mysql-4.1 @@ -362,7 +362,7 @@

-

Requirements

+

Requirements

An adequate solution must meet all of the following requirements:

Preemptive
@@ -418,9 +418,9 @@
-

Specification

+

Specification

-

Overview

+

Overview

News items are published and delivered to users as follows:

  1. A news item is written. The format to be used is described below.
  2. @@ -441,7 +441,7 @@
-

Required Portage Enhancements

+

Required Portage Enhancements

The following extensions to Portage are required:

-

News Item Identities

+

News Item Identities

Each news item will have a unique identifier. This identifier will be in the form yyyy-mm-dd-short-name, where yyyy is the year (e.g. 2005), mm is the month (01 through 12) and dd is the day of the month @@ -473,7 +473,7 @@ 0-9, + (plus), - (hyphen) and _ (underscore).

-

News Item Directories

+

News Item Directories

Each news item will be represented by a directory whose name is the same as the news item's identifier.

The directory will contain a file named yyyy-mm-dd-short-name.en.txt, which @@ -485,7 +485,7 @@ justified by precedent [8].

-

News Item Files

+

News Item Files

A news item file is a text file, encoded using UTF-8 [14] for compatibility with and for the same reasons as existing Gentoo documentation [2] and the tree [7].

@@ -501,7 +501,7 @@ various optional and mandatory headers. Future GLEPs may propose new headers — tools handling these news items must ignore any unrecognised header.

-

News Item Headers

+

News Item Headers

The following headers describe the purpose and format of the news item:

Title:
@@ -569,7 +569,7 @@ people who use YourSQL and who are on both sparc and x86-obsd".

-

News Item Body

+

News Item Body

The header section must be followed by a blank line, then the main body of the text.

The text body should be wrapped at 72 characters. No fancy formatting or tab @@ -582,13 +582,13 @@ administrated — this will be the case on many servers and routers, for example.

-

Example News Item

-

This hypothetical news item [16] could be used for an upgrade to the +

Example News Item

+

This hypothetical news item [18] could be used for an upgrade to the YourSQL database format which breaks forward compatibility.

-

News Item Quality Control

+

News Item Quality Control

There have been complaints regarding the comprehensibility of some upgrade notices and news items in the past. This is understandable — not every Gentoo developer speaks English as a first language. However, for the sake of clarity, @@ -612,9 +612,9 @@

-

News Item Distribution

+

News Item Distribution

-

Server Side

+

Server Side

News items are to be made available via the standard rsync tree. This removes any need for polling of a remote source.

A new repository will be created for news items. The type (CVS or Subversion), @@ -639,7 +639,7 @@ directory.

-

Client Side

+

Client Side

Whenever relevant unread news items are found, the package manager will create a file named /var/lib/gentoo/news/news-${repoid}.unread (if it does not already exist) and append the news item identifier (eg @@ -675,7 +675,7 @@

-

News Item Clients

+

News Item Clients

Once a news item is marked for reading, third party tools (or traditional core Unix tools) can be used to display and view the news files.

When a news item is read, its name should be removed from the @@ -688,7 +688,7 @@ desire them.

-

News Item Removal

+

News Item Removal

News items can be removed (by removing the news file from the main tree) when they are no longer relevant, if they are made obsolete by a future news item or after a long period of time. This is the same as the method used for updates @@ -696,39 +696,41 @@

-

Integration with Existing Systems

+

Integration with Existing Systems

It would be simple to convert these news items into the format used for news items on the Gentoo website or posts for the gentoo-announce mailing list.

There is an existing automated tool [4] for posting GLSAs to the forums. A similar tool can be used for these news items.

-

Backwards Compatibility

+

Backwards Compatibility

Backwards compatibility is not a concern here. Existing tools will simply ignore the news/ directory.

-

Reference Implementation

-

TODO

+

Reference Implementation

+

A reference implementation of the required package manager support can be found +in Paludis [15], along with a reference newsreader implemented as an +eselect module [16].

-

Credits

+

Credits

The idea behind notifying users of news updates via Portage comes from Stuart -Herbert [15].

+Herbert [17].

Thanks to Lance Albertson, Stephen Bennett, Donnie Berkholz, Grant Goodyear, Brian Harring, Marius Mauch, Dan Meltzer, Jason Stubbs, Paul de Vrieze and Alec Warner for input. Some of the ideas presented here are theirs, others go completely against their suggestions.

-

Example Files

+

Example Files

example-news-item.txt
An example news item.
-

References

+

References

@@ -831,22 +833,34 @@ http://www.ietf.org/rfc/rfc3629.txt
+ + + + + +
[15]Paludis homepage, http://paludis.berlios.de
+ + + + + +
[16]news.eselect, http://svn.berlios.de/svnroot/repos/paludis/trunk/eselect/news.eselect
-
[15]"Favouring an automatic news mechanism", Stuart Herbert, +
[17]"Favouring an automatic news mechanism", Stuart Herbert, http://stu.gnqs.org/diary/gentoo.php/2005/10/28/favouring_an_automatic_news_mechanism
- +
- +
[16]glep-0042-extras/example-news-item.txt
[18]glep-0042-extras/example-news-item.txt
-

Copyright

+

Copyright

This document has been placed in the public domain.

@@ -855,7 +869,7 @@