GLEP 42: Critical News Reporting

News Item Headers

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

Title:

A short (maximum 50 characters) descriptive title. Mandatory.

Author:

Author's name and email address, in the form Real Name <email@address>. Mandatory; multiple author headers may be specified if appropriate.

Translator:

For translated news items, the translator's name and email address. Multiple translator headers may be specified if appropriate.

Content-Type:

Only in news item format 1.0, where it is mandatory and must be text/plain.

Posted:

Date of posting, in yyyy-mm-dd format (e.g. 2005-12-18) for compatibility with GLEP 45 [10]. The date must be represented in UTC (Coordinated Universal Time). Translations should use the date of the original news item. Mandatory.

Revision:

Initially 1. Should be incremented every time a change is made to the news item. Changes that require a re-read of the news item (i.e., most changes that are not spelling or formatting related) should instead use a new news item. Mandatory.

News-Item-Format:

Known formats are 1.0 and 2.0. Future revisions to the format may increment the minor number for forwards-compatible changes (i.e., still allowing older tools to process the new format), or the major number for major changes.

The following headers are used for filtering:

Display-If-Installed:

A package dependency specification (for example, >=sys-devel/gcc-5 or www-servers/apache) conforming to EAPI 0 [18] in news item format 1.0 or to EAPI 5 in format 2.0. If the user has the package specified installed from the repository from which the news item was obtained, the news item should be displayed.

Display-If-Keyword:

A keyword [7] name, for example mips or x86-fbsd. If the user is on the keyword in question, the news item should be displayed.

Display-If-Profile:

A profile path, for example default/linux/sparc/13.0. If the user is using the exact profile in question, the news item should be displayed. This header may be used to replace deprecated files in the future. In news item format 2.0, a terminal asterisk immediately following a slash acts as a wildcard for any further path components, for example default/linux/*.

The algorithm used to determine whether a news item is 'relevant' is as follows:

• For each Display-If- header type which occurs at least once:
  • The news item is not relevant if none of the headers of this type are successfully matched.
• Otherwise the news item is relevant.

In particular, if no Display-If- header is specified, a news item will be relevant for all users.

This algorithm was chosen because it makes conditions like "display this news item for YourSQL users who are on sparc or x86-obsd relatively simple to specify — it is believed that these kinds of condition are far more likely to occur than "display this news item for people using YourSQL, or 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

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 characters should be used — the news item may be being displayed directly to a terminal. Paragraphs should be separated by a blank line.

Hyperlinks may be used to refer to further information (for example, an upgrade guide). However, the main body of the news item should be descriptive and not simply a "read this link" text. It is assumed that the user will have access to 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

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

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), location and access controls on this repository are beyond the scope of this GLEP.

The contents of this repository will automatically be merged with the main rsync tree, placing the items in a metadata/news/ directory. The method used for merging these items and the frequency at which it will occur is beyond the scope of this GLEP; a similar setup is already used for merging GLSAs into the rsync tree.

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 2005-11-01-yoursql-updates) on a new line.

All news item related files should be root owned and in the portage group with the group write (and, for directories, execute) bits set. News files should be world readable.

Notification that new relevant news items will be displayed via the emerge tool in a similar way to the existing "configuration files need updating" messages:

* Important: there are 5 unread news items.
* Type emerge --help news to learn how to read news files.

Checks for new news messages should be displayed:

• After an emerge sync
• After an emerge --pretend
• Before an emerge <target> (which may also include a red warning message)

The package manager does not need to know how to launch the user's choice of news client. This is consistent with the way configuration file updates are handled.

The package manager may use a timestamp check file to avoid having to process news items unnecessarily.

The package manager must keep track of news items that have already been added to the unread list to avoid repeatedly marking a deleted news item. This could be handled via a news-${repoid}.skip file containing the IDs of news items that have already been added to a news-${repoid}.unread file, but this method is not required by this GLEP.

Users who really don't care about news items can use rsync_excludes to filter out the metadata/news/ directory.