--- xml/htdocs/proj/en/glep/glep-0042.html 2006/01/05 15:10:45 1.7 +++ xml/htdocs/proj/en/glep/glep-0042.html 2006/02/13 16:26:47 1.8 @@ -8,7 +8,7 @@ --> - + GLEP 42 -- Critical News Reporting @@ -21,8 +21,8 @@ border="0" width="150" height="35" /> [Gentoo Linux Home] -[GLEP Index] -[GLEP Source] +[GLEP Index] +[GLEP Source] @@ -32,17 +32,17 @@ - + - + - + @@ -51,8 +51,8 @@
Title:Critical News Reporting
Version:$Revision: 1.7 $
Version:1.7
Author:Ciaran McCreesh <ciaranm at gentoo.org>
Last-Modified:$Date: 2006/01/05 15:10:45 $
Last-Modified:2006/01/05 15:10:45
Status:Draft
Type:Standards Track
Content-Type:text/x-rst
Content-Type:text/x-rst
Created:31-Oct-2005

-
-

Contents

+
+

Contents

-
-

Abstract

+
+

Abstract

This GLEP proposes a new way of informing users about important updates and news regarding tree-related items.

-
-

Motivation

+
+

Motivation

Although most package updates are clean and require little user action, occasionally an upgrade requires user intervention during the upgrade process. Recent examples of the latter include the gcc-3.4 stabilisation on x86 @@ -123,8 +123,8 @@ by elog [1].

-
-

Requirements

+
+

Requirements

An adequate solution must meet all of the following requirements:

Preemptive
@@ -179,10 +179,10 @@ sources should not be precluded.
-
-

Specification

-
-

Overview

+
+

Specification

+
+

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. @@ -202,8 +202,8 @@ Item Clients.
-
-

Required Portage Enhancements

+
+

Required Portage Enhancements

The following extensions to Portage are required:

  • Every repository (including overlays) will require a unique identifier. It is @@ -224,8 +224,8 @@

These extensions are assumed during the following specification.

-
-

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 @@ -233,8 +233,8 @@ news item (e.g. yoursql-updates), consisting only of the characters a-z, 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 @@ -244,8 +244,8 @@ provided. However, only the English version of a news item is authoritative. This anglocentricity is 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].

@@ -260,8 +260,8 @@ followed by the main body of the message as plain text. This GLEP defines 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:
@@ -327,8 +327,8 @@ for people on sparc or x86-obsd" or "display these news items for 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 @@ -340,14 +340,14 @@ a web browser somewhere, but not necessarily on the box which is being administrated — this will be the case on many servers and routers, for example.

-
-

Example News Item

+
+

Example News Item

This hypothetical news item [16] 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, @@ -370,10 +370,10 @@ YourSQL users because ...", not "YourSQL is important because ...".

-
-

News Item Distribution

-
-

Server Side

+
+

News Item Distribution

+
+

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), @@ -397,8 +397,8 @@ news item directories will all be immediately under the metadata/news/ 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 @@ -433,8 +433,8 @@ filter out the metadata/news/ directory.

-
-

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 @@ -446,43 +446,43 @@ be ideal for users who sync on a cron) are left as options for those who 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 entries.

-
-

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

-
-

Portage Code

+
+

Reference Implementation

+
+

Portage Code

TODO

-
-

Simple eselect News Client

+
+

Simple eselect News Client

TODO Removed until the exact format details are figured out.

-
-

Simple News to Mail Forwarder

+
+

Simple News to Mail Forwarder

TODO Removed until the exact format details are figured out.

-
-

Credits

+
+

Credits

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

Thanks to Lance Albertson, Stephen Bennett, Donnie Berkholz, Grant Goodyear, @@ -490,12 +490,12 @@ Warner for input. Some of the ideas presented here are theirs, others go completely against their suggestions.

-
-

Example Files

+
+

Example Files

TODO Removed until the exact format details are figured out.

-
-

References

+
+

References

@@ -612,8 +612,8 @@
-