--- xml/htdocs/proj/en/glep/glep-0042.html 2005/12/13 03:21:59 1.5 +++ xml/htdocs/proj/en/glep/glep-0042.html 2005/12/18 04:16:44 1.6 @@ -32,11 +32,11 @@
The following extensions to Portage are required:+
TODO: ferringb wants spaces added to the first item on the list. I don't, +because it makes repo id -> filename mappings nasty.+
These extensions are assumed during the following specification.+
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 (01 through 31). The short-name is a very short name describing the news item (e.g. yoursql-updates), consisting only of the characters a-z, -0-9, + (plus), : (colon) and - (hyphen).+0-9, + (plus), : (colon), - (hyphen) and _ (underscore).
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 @@ -219,13 +244,13 @@
If a news item is translated, other files named yyyy-mm-dd-short-name.xx.txt (where xx is the ISO 639  two letter country code) will also be provided. However, only the English version of a news item is authoritative. -This anglocentricity is justified by precedent .+This anglocentricity is justified by precedent .
News items should be signed with a detached GPG signature:
gpg --armour --detach-sign ????-??-??-*.??.txt @@ -235,7 +260,7 @@ various optional and mandatory headers. Future GLEPs may propose new headers — tools handling these news items must ignore any unrecognised header.-
The following headers describe the purpose and format of the news item:
- Title:@@ -249,9 +274,8 @@
- Must be text/plain. Mandatory.
- Date of posting, in dd-mmm-yyyy format (e.g. 14-Aug-2001) for -compatibility with GLEP 1 . UTC time in hh-mm-ss +0000 format -may also be included. Mandatory.+
- Date of posting, in yyyy-mm-dd format (e.g. 2005-12-18) for +compatibility with GLEP 45 . Mandatory.
- Initially 1. Incremented every time a non-trivial change is made. Changes which require a re-read of the news item should instead use a new news item @@ -266,14 +290,15 @@
- A dependency atom or simple package name (for example, <dev-lang/php-5_alpha or net-www/apache). If the user has the -package specified installed, the news item should be displayed.+package specified installed from the repository from which the news item was +obtained, the news item should be displayed.
- A keyword  name, for example mips or x86-fbsd. If the +
- A keyword  name, for example mips or x86-fbsd. If the user is on the keyword in question, the news item should be displayed.
- A profile path, for example default-linux/sparc/sparc64/server. Standard -shell GLOB wildcards may be used. If the user is using the exact profile in -question, the news item should be displayed. This header may be used to +
- A profile path, for example default-linux/sparc/sparc64/server. If the +user is using the exact profile in question, or a subprofile of this +profile, the news item should be displayed. This header may be used to replace deprecated files in the future.@@ -301,7 +326,7 @@ people who use YourSQL and who are on both sparc and x86-obsd".-
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 @@ -314,13 +339,13 @@ administrated — this will be the case on may servers and routers, for example.-
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, @@ -352,9 +377,9 @@
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), @@ -376,19 +401,11 @@
The main rsync tree will not use the yyyy/mm/ subdirectory layout.
Whenever relevant unread news items are found, the package manager will create a -file named /var/lib/gentoo/news/news-magic-chicken.unread (if it does not +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.-
Future changes to Portage involving support for multiple repositories -may introduce repository names. In this case, the magic-chicken part of the -filename should be replaced by a string representation of the repository -name. Thus, news item clients should use a wildcard rather than hardcoding -the magic-chicken string.-
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:@@ -407,28 +424,28 @@ 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-magic-chicken.skip file, but implementation is not -specified by this GLEP.+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.
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 -news-magic-chicken.unread file. If a news client acts as an interactive -reader rather than a gateway, it should then add the name to a -news-magic-chicken.read file in the same directory with the same file -format (again, magic-chicken should be a wildcard rather than hardcoded).+news-repoid.unread file. If a news client acts as an interactive reader +rather than a gateway, it should then add the name to a news-repoid.read +file in the same directory with the same file format.
An eselect  module shall be created as the 'suggested' display tool; other display tools (for example, a news to email forwarder, which would be ideal for users who sync on a cron) are left as options for those who desire them.
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 @@ -436,34 +453,34 @@
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  for posting GLSAs to the forums. A similar tool can be used for these news items.
Backwards compatibility is not a concern here. Existing tools will simply ignore the news/ directory.
TODO Removed until the exact format details are figured out.
The idea behind notifying users of news updates via Portage comes from Stuart Herbert .
Thanks to Lance Albertson, Stephen Bennett, Donnie Berkholz, Grant Goodyear, @@ -472,11 +489,11 @@ against their suggestions.
|||GLEP 1: "GLEP Purpose and Guidelines", Grant Goodyear, -http://www.gentoo.org/proj/en/glep/glep-0001.html|
|||GLEP 22: "New "keyword" system to incorporate various +|
|||GLEP 22: "New "keyword" system to incorporate various userlands/kernels/archs", Grant Goodyear, http://www.gentoo.org/proj/en/glep/glep-0022.html|
|||GLEP 31: "Character Sets for Portage Tree Items", Ciaran +|
|||GLEP 31: "Character Sets for Portage Tree Items", Ciaran McCreesh, http://www.gentoo.org/proj/en/glep/glep-0031.html|
|||GLEP 34: "Per-Category metadata.xml Files", Ciaran McCreesh, +|
|||GLEP 34: "Per-Category metadata.xml Files", Ciaran McCreesh, http://www.gentoo.org/proj/en/glep/glep-0034.html|
|||GLEP 36: "Subversion/CVS for Gentoo Hosted Projects", Aaron +|
|||GLEP 36: "Subversion/CVS for Gentoo Hosted Projects", Aaron Walker, http://www.gentoo.org/proj/en/glep/glep-0036.html|
|||GLEP 45: "GLEP date format", Henrik Brix Andersen, +http://www.gentoo.org/proj/en/glep/glep-0045.html|