/[gentoo]/xml/htdocs/proj/en/glep/glep-0042.txt

Diff of /xml/htdocs/proj/en/glep/glep-0042.txt

Parent Directory | Revision Log | View Patch Patch

Revision 1.5		Revision 1.6
1	GLEP: 42	1	GLEP: 42
2	Title: Critical News Reporting	2	Title: Critical News Reporting
3	Version: $Revision: 1.5 $	3	Version: $Revision: 1.6 $
4	Author: Ciaran McCreesh <ciaranm@gentoo.org>	4	Author: Ciaran McCreesh <ciaranm@gentoo.org>
5	Last-Modified: $Date: 2005/12/13 03:21:59 $	5	Last-Modified: $Date: 2005/12/18 04:16:44 $
6	Status: Draft	6	Status: Draft
7	Type: Standards Track	7	Type: Standards Track
8	Content-Type: text/x-rst	8	Content-Type: text/x-rst
9	Created: 31-Oct-2005	9	Created: 31-Oct-2005
10	Post-History: 1-Nov-2005, 5-Nov-2005, 7-Nov-2005, 11-Dec-2005, 13-Dec-2005	10	Post-History: 1-Nov-2005, 5-Nov-2005, 7-Nov-2005, 11-Dec-2005, 13-Dec-2005, 18-Dec-2005
11		11
12	Abstract	12	Abstract
13	========	13	========
14		14
15	This GLEP proposes a new way of informing users about important updates and news	15	This GLEP proposes a new way of informing users about important updates and news
…		…
134	informing the user that there are unread news items.	134	informing the user that there are unread news items.
135		135
136	6. The news item is handled by the user's choice of news item reader. See `News	136	6. The news item is handled by the user's choice of news item reader. See `News
137	Item Clients`_.	137	Item Clients`_.
138		138
		139	Required Portage Enhancements
		140	-----------------------------
		141
		142	The following extensions to Portage are required:
		143
		144	TODO: ferringb wants spaces added to the first item on the list. I don't,
		145	because it makes repo id -> filename mappings nasty.
		146
		147	* Every repository (including overlays) will require a unique identifier. It is
		148	assumed that an identifier will be a string consisting of characters from
		149	``a`` to ``z``, ``A`` to ``Z``, ``0`` to ``9``, ``+`` (plus), ``-`` (hyphen),
		150	``:`` (colon) and ``_`` (underscore).
		151
		152	* Portage must provide a way for external programs to obtain a list of all
		153	repository identifiers for a given system. It is assumed that this will be in
		154	the form of a ``portageq`` command (e.g. ``portageq get_repo_ids``).
		155
		156	* Portage must provide a way for external programs to obtain the base path for
		157	a repository with a given ID. It is assumed that this will be in the form of
		158	a ``portageq`` command (e.g. ``portageq get_repo_root gentoo-x86``).
		159
		160	* Portage must extend ``portageq has_version`` to support restrictions to a
		161	given repository ID.
		162
		163	* Portage must extend ``portageq`` to implement a command which returns whether
		164	or not the profile used for a given repository ID matches a certain base path
		165	(e.g. ``portageq profile_used default-linux/sparc/sparc64/2004.3 gentoo-x86``).
		166
		167	These extensions are assumed during the following specification.
		168
139	News Item Identities	169	News Item Identities
140	--------------------	170	--------------------
141		171
142	Each news item will have a unique identifier. This identifier will be in the	172	Each news item will have a unique identifier. This identifier will be in the
143	form ``yyyy-mm-dd-short-name``, where ``yyyy`` is the year (e.g. ``2005``),	173	form ``yyyy-mm-dd-short-name``, where ``yyyy`` is the year (e.g. ``2005``),
144	``mm`` is the month (``01`` through ``12``) and dd is the day of the month	174	``mm`` is the month (``01`` through ``12``) and dd is the day of the month
145	(``01`` through ``31``). The ``short-name`` is a very short name describing the	175	(``01`` through ``31``). The ``short-name`` is a very short name describing the
146	news item (e.g. ``yoursql-updates``), consisting only of the characters ``a-z``,	176	news item (e.g. ``yoursql-updates``), consisting only of the characters ``a-z``,
147	``0-9``, ``+`` (plus), ``:`` (colon) and ``-`` (hyphen).	177	``0-9``, ``+`` (plus), ``:`` (colon), ``-`` (hyphen) and ``_`` (underscore).
148		178
149	News Item Directories	179	News Item Directories
150	---------------------	180	---------------------
151		181
152	Each news item will be represented by a directory whose name is the same as the	182	Each news item will be represented by a directory whose name is the same as the
…		…
194		224
195	``Content-Type:``	225	``Content-Type:``
196	Must be ``text/plain``. Mandatory.	226	Must be ``text/plain``. Mandatory.
197		227
198	``Posted:``	228	``Posted:``
199	Date of posting, in ``dd-mmm-yyyy`` format (e.g. 14-Aug-2001) for	229	Date of posting, in ``yyyy-mm-dd`` format (e.g. 2005-12-18) for
200	compatibility with GLEP 1 [#glep-1]_. UTC time in ``hh-mm-ss +0000`` format	230	compatibility with GLEP 45 [#glep-45]_. Mandatory.
201	may also be included. Mandatory.
202		231
203	``Revision:``	232	``Revision:``
204	Initially 1. Incremented every time a non-trivial change is made. Changes	233	Initially 1. Incremented every time a non-trivial change is made. Changes
205	which require a re-read of the news item should instead use a new news item	234	which require a re-read of the news item should instead use a new news item
206	file. Mandatory.	235	file. Mandatory.
…		…
213	The following headers are used for filtering:	242	The following headers are used for filtering:
214		243
215	``Display-If-Installed:``	244	``Display-If-Installed:``
216	A dependency atom or simple package name (for example,	245	A dependency atom or simple package name (for example,
217	``<dev-lang/php-5_alpha`` or ``net-www/apache``). If the user has the	246	``<dev-lang/php-5_alpha`` or ``net-www/apache``). If the user has the
		247	package specified installed from the repository from which the news item was
218	package specified installed, the news item should be displayed.	248	obtained, the news item should be displayed.
219		249
220	``Display-If-Keyword:``	250	``Display-If-Keyword:``
221	A keyword [#glep-22]_ name, for example ``mips`` or ``x86-fbsd``. If the	251	A keyword [#glep-22]_ name, for example ``mips`` or ``x86-fbsd``. If the
222	user is on the keyword in question, the news item should be displayed.	252	user is on the keyword in question, the news item should be displayed.
223		253
224	``Display-If-Profile:``	254	``Display-If-Profile:``
225	A profile path, for example ``default-linux/sparc/sparc64/server``. Standard	255	A profile path, for example ``default-linux/sparc/sparc64/server``. If the
226	shell GLOB wildcards may be used. If the user is using the exact profile in	256	user is using the exact profile in question, or a subprofile of this
227	question, the news item should be displayed. This header may be used to	257	profile, the news item should be displayed. This header may be used to
228	replace ``deprecated`` files in the future.	258	replace ``deprecated`` files in the future.
229		259
230	.. Note:: When performing package moves, developers must also update any	260	.. Note:: When performing package moves, developers must also update any
231	relevant ``Display-If-Installed`` headers in news files.	261	relevant ``Display-If-Installed`` headers in news files.
232		262
…		…
335		365
336	Client Side	366	Client Side
337	'''''''''''	367	'''''''''''
338		368
339	Whenever relevant unread news items are found, the package manager will create a	369	Whenever relevant unread news items are found, the package manager will create a
340	file named ``/var/lib/gentoo/news/news-magic-chicken.unread`` (if it does not	370	file named ``/var/lib/gentoo/news/news-repoid.unread`` (if it does not
341	already exist) and append the news item identifier (eg	371	already exist) and append the news item identifier (eg
342	``2005-11-01-yoursql-updates``) on a new line.	372	``2005-11-01-yoursql-updates``) on a new line.
343
344	.. Note:: Future changes to Portage involving support for multiple repositories
345	may introduce repository names. In this case, the ``magic-chicken`` part of the
346	filename should be replaced by a string representation of the repository
347	name. Thus, news item clients should use a wildcard rather than hardcoding
348	the ``magic-chicken`` string.
349		373
350	Notification that new relevant news items will be displayed via the	374	Notification that new relevant news items will be displayed via the
351	``emerge`` tool in a similar way to the existing "configuration files need	375	``emerge`` tool in a similar way to the existing "configuration files need
352	updating" messages:	376	updating" messages:
353		377
…		…
366	The package manager may use a timestamp check file to avoid having to process	390	The package manager may use a timestamp check file to avoid having to process
367	news items unnecessarily.	391	news items unnecessarily.
368		392
369	The package manager must keep track of news items that have already been added	393	The package manager must keep track of news items that have already been added
370	to the unread list to avoid repeatedly marking a deleted news item. This could	394	to the unread list to avoid repeatedly marking a deleted news item. This could
371	be handled via a ``news-magic-chicken.skip`` file, but implementation is not	395	be handled via a ``news-repoid.skip`` file containing the IDs of news items that
		396	have already been added to a ``news-repoid.unread`` file, but this method is not
372	specified by this GLEP.	397	required by this GLEP.
373		398
374	Users who really don't care about news items can use ``rsync_excludes`` to	399	Users who really don't care about news items can use ``rsync_excludes`` to
375	filter out the ``metadata/news/`` directory.	400	filter out the ``metadata/news/`` directory.
376		401
377	News Item Clients	402	News Item Clients
…		…
379		404
380	Once a news item is marked for reading, third party tools (or traditional core	405	Once a news item is marked for reading, third party tools (or traditional core
381	Unix tools) can be used to display and view the news files.	406	Unix tools) can be used to display and view the news files.
382		407
383	When a news item is read, its name should be removed from the	408	When a news item is read, its name should be removed from the
384	``news-magic-chicken.unread`` file. If a news client acts as an interactive	409	``news-repoid.unread`` file. If a news client acts as an interactive reader
385	reader rather than a gateway, it should then add the name to a	410	rather than a gateway, it should then add the name to a ``news-repoid.read``
386	``news-magic-chicken.read`` file in the same directory with the same file	411	file in the same directory with the same file format.
387	format (again, ``magic-chicken`` should be a wildcard rather than hardcoded).
388		412
389	An ``eselect`` [#eselect]_ module shall be created as the 'suggested' display	413	An ``eselect`` [#eselect]_ module shall be created as the 'suggested' display
390	tool; other display tools (for example, a news to email forwarder, which would	414	tool; other display tools (for example, a news to email forwarder, which would
391	be ideal for users who sync on a ``cron``) are left as options for those who	415	be ideal for users who sync on a ``cron``) are left as options for those who
392	desire them.	416	desire them.
…		…
461	http://www.gentoo.org/proj/en/eselect/index.xml	485	http://www.gentoo.org/proj/en/eselect/index.xml
462	.. [#forums-glsa] Forums user GLSA,	486	.. [#forums-glsa] Forums user GLSA,
463	http://forums.gentoo.org/profile.php?mode=viewprofile&u=55648	487	http://forums.gentoo.org/profile.php?mode=viewprofile&u=55648
464	.. [#forums-apache2] Forums thread "Gentoo Apache2 Config Change Idiocy",	488	.. [#forums-apache2] Forums thread "Gentoo Apache2 Config Change Idiocy",
465	http://forums.gentoo.org/viewtopic-t-384368.html	489	http://forums.gentoo.org/viewtopic-t-384368.html
466	.. [#glep-1] GLEP 1: "GLEP Purpose and Guidelines", Grant Goodyear,
467	http://www.gentoo.org/proj/en/glep/glep-0001.html
468	.. [#glep-22] GLEP 22: "New "keyword" system to incorporate various	490	.. [#glep-22] GLEP 22: "New "keyword" system to incorporate various
469	userlands/kernels/archs", Grant Goodyear,	491	userlands/kernels/archs", Grant Goodyear,
470	http://www.gentoo.org/proj/en/glep/glep-0022.html	492	http://www.gentoo.org/proj/en/glep/glep-0022.html
471	.. [#glep-31] GLEP 31: "Character Sets for Portage Tree Items", Ciaran	493	.. [#glep-31] GLEP 31: "Character Sets for Portage Tree Items", Ciaran
472	McCreesh,	494	McCreesh,
…		…
474	.. [#glep-34] GLEP 34: "Per-Category metadata.xml Files", Ciaran McCreesh,	496	.. [#glep-34] GLEP 34: "Per-Category metadata.xml Files", Ciaran McCreesh,
475	http://www.gentoo.org/proj/en/glep/glep-0034.html	497	http://www.gentoo.org/proj/en/glep/glep-0034.html
476	.. [#glep-36] GLEP 36: "Subversion/CVS for Gentoo Hosted Projects", Aaron	498	.. [#glep-36] GLEP 36: "Subversion/CVS for Gentoo Hosted Projects", Aaron
477	Walker,	499	Walker,
478	http://www.gentoo.org/proj/en/glep/glep-0036.html	500	http://www.gentoo.org/proj/en/glep/glep-0036.html
		501	.. [#glep-45] GLEP 45: "GLEP date format", Henrik Brix Andersen,
		502	http://www.gentoo.org/proj/en/glep/glep-0045.html
479	.. [#iso-639] ISO 639 "Code for the representation of names of languages"	503	.. [#iso-639] ISO 639 "Code for the representation of names of languages"
480	.. [#ramereth-repo] "Re: [gentoo-dev] GLEP ??: Critical News Reporting", Lance	504	.. [#ramereth-repo] "Re: [gentoo-dev] GLEP ??: Critical News Reporting", Lance
481	Albertson,	505	Albertson,
482	http://marc.theaimsgroup.com/?l=gentoo-dev&m=113111585907703&w=2	506	http://marc.theaimsgroup.com/?l=gentoo-dev&m=113111585907703&w=2
483	.. [#rfc-822] RFC 822 "Standard for the format of ARPA Internet text messages"	507	.. [#rfc-822] RFC 822 "Standard for the format of ARPA Internet text messages"

 Legend:



Removed from v.1.5
 


changed lines


 
Added in v.1.6
 Legend:



Removed from v.1.5
 


changed lines


 
Added in v.1.6
-Removed from v.1.5
+Added in v.1.6

	ViewVC Help
Powered by ViewVC 1.1.13