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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.7 Revision 1.14
1GLEP: 42 1GLEP: 42
2Title: Critical News Reporting 2Title: Critical News Reporting
3Version: $Revision: 1.7 $ 3Version: $Revision: 1.14 $
4Author: Ciaran McCreesh <ciaranm@gentoo.org> 4Author: Ciaran McCreesh <ciaranm@gentoo.org>,
5 Stephen Bennett <spb@gentoo.org>,
6 Zach Medico <zmedico@gentoo.org>
5Last-Modified: $Date: 2006/01/05 15:10:45 $ 7Last-Modified: $Date: 2010/02/22 11:38:26 $
6Status: Draft 8Status: Final
7Type: Standards Track 9Type: Standards Track
8Content-Type: text/x-rst 10Content-Type: text/x-rst
9Created: 31-Oct-2005 11Created: 31-Oct-2005
10Post-History: 1-Nov-2005, 5-Nov-2005, 7-Nov-2005, 11-Dec-2005, 13-Dec-2005, 18-Dec-2005, 5-Jan-2006 12Post-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, 5-Sep-2006
11 13
12Abstract 14Abstract
13======== 15========
14 16
15This GLEP proposes a new way of informing users about important updates and news 17This GLEP proposes a new way of informing users about important updates and news
16regarding tree-related items. 18related to the tree.
17 19
18Motivation 20Motivation
19========== 21==========
20 22
21Although most package updates are clean and require little user action, 23Although most package updates are clean and require little user action,
22occasionally an upgrade requires user intervention during the upgrade process. 24occasionally an upgrade requires user intervention. Recent examples of the
23Recent examples of the latter include the ``gcc-3.4`` stabilisation on ``x86`` 25latter include the ``gcc-3.4`` stabilisation on ``x86`` and the ``mysql-4.1``
24and the ``mysql-4.1`` database format changes. 26database format changes.
25 27
26There are currently several ways of delivering important news items to our 28There are currently several ways of delivering important news items to our
27users, none of them particularly effective: 29users, none of them particularly effective:
28 30
29* Gentoo Weekly News 31* Gentoo Weekly News
32* The main Gentoo website 34* The main Gentoo website
33* RSS feeds of Gentoo news 35* RSS feeds of Gentoo news
34* ``einfo`` and ``ewarn`` messages in ``pkg_setup`` or ``pkg_postinst`` 36* ``einfo`` and ``ewarn`` messages in ``pkg_setup`` or ``pkg_postinst``
35 37
36A more reliable way of getting news of critical updates out to users is required 38A more reliable way of getting news of critical updates out to users is required
37to avoid repeats of the various recent upgrade debacles. This GLEP proposes a 39to avoid repeats of various prior upgrade debacles. This GLEP proposes a
38solution based around pushing news items out to the user via the ``rsync`` tree. 40solution based around pushing news items out to the user via the ``rsync`` tree.
39 41
40.. Important:: This GLEP does not seek to replace or modify ``einfo`` messages 42.. Important:: This GLEP does not seek to replace or modify ``einfo`` messages
41 which are displayed post-install. That is a separate issue which is handled 43 which are displayed post-install. That is a separate issue which is handled
42 by ``elog`` [#bug-11359]_. 44 by ``elog`` [#bug-11359]_.
52 given ample warning to plan difficult upgrades and changes, rather than only 54 given ample warning to plan difficult upgrades and changes, rather than only
53 being told just before action is necessary. 55 being told just before action is necessary.
54 56
55No user subscription required 57No user subscription required
56 It has already been demonstrated [#forums-apache2]_ that many users do not 58 It has already been demonstrated [#forums-apache2]_ that many users do not
57 read the ``gentoo-announce`` mailing list or ``RSS`` feeds. A solution which 59 read the ``gentoo-announce`` mailing list or ``RSS`` feeds. A solution that
58 requires subscription has no advantage over current methods. 60 requires subscription has no advantage over current methods.
59 61
60No user monitoring required 62No user monitoring required
61 It has already been demonstrated [#forums-apache2]_ that many users do not 63 It has already been demonstrated [#forums-apache2]_ that many users do not
62 read news items posted to the Gentoo website, or do not read news items 64 read news items posted to the Gentoo website, or do not read news items
156 158
157* Portage must extend ``portageq has_version`` to support restrictions to a 159* Portage must extend ``portageq has_version`` to support restrictions to a
158 given repository ID. 160 given repository ID.
159 161
160* Portage must extend ``portageq`` to implement a command which returns whether 162* Portage must extend ``portageq`` to implement a command which returns whether
161 or not the profile used for a given repository ID matches a certain base path 163 or not the profile used for a given repository ID is exactly the given profile
162 (e.g. ``portageq profile_used default-linux/sparc/sparc64/2004.3 gentoo-x86``). 164 (e.g. ``portageq profile_used default-linux/sparc/sparc64/2004.3
165 gentoo-x86``).
163 166
164These extensions are assumed during the following specification. 167These extensions are assumed during the following specification.
165 168
166News Item Identities 169News Item Identities
167-------------------- 170--------------------
181 184
182The directory will contain a file named ``yyyy-mm-dd-short-name.en.txt``, which 185The directory will contain a file named ``yyyy-mm-dd-short-name.en.txt``, which
183contains the text of the news item, in English, in the format described below. 186contains the text of the news item, in English, in the format described below.
184 187
185If a news item is translated, other files named ``yyyy-mm-dd-short-name.xx.txt`` 188If a news item is translated, other files named ``yyyy-mm-dd-short-name.xx.txt``
186(where ``xx`` is the ISO 639 [#iso-639]_ two letter country code) will also be 189(where ``xx`` is the ISO 639 [#iso-639]_ two letter country code, and the date
187provided. However, only the English version of a news item is authoritative. 190remains the same as the original news item) will also be provided. However, only
188This anglocentricity is justified by precedent [#glep-34]_. 191the English version of a news item is authoritative. This anglocentricity is
192justified by precedent [#glep-34]_.
189 193
190News Item Files 194News Item Files
191--------------- 195---------------
192 196
193A news item file is a text file, encoded using UTF-8 [#rfc-3629]_ for 197A news item file is a text file, encoded using UTF-8 [#rfc-3629]_ for
226``Content-Type:`` 230``Content-Type:``
227 Must be ``text/plain``. Mandatory. 231 Must be ``text/plain``. Mandatory.
228 232
229``Posted:`` 233``Posted:``
230 Date of posting, in ``yyyy-mm-dd`` format (e.g. 2005-12-18) for 234 Date of posting, in ``yyyy-mm-dd`` format (e.g. 2005-12-18) for
231 compatibility with GLEP 45 [#glep-45]_. Mandatory. 235 compatibility with GLEP 45 [#glep-45]_. Translations should use the date
236 of the original news item. Mandatory.
232 237
233``Revision:`` 238``Revision:``
234 Initially 1. Should be incremented every time a change is made to the news 239 Initially 1. Should be incremented every time a change is made to the news
235 item. Changes that require a re-read of the news item (i.e., most changes 240 item. Changes that require a re-read of the news item (i.e., most changes
236 that are not spelling or formatting related) should instead use a new news 241 that are not spelling or formatting related) should instead use a new news
253 A keyword [#glep-22]_ name, for example ``mips`` or ``x86-fbsd``. If the 258 A keyword [#glep-22]_ name, for example ``mips`` or ``x86-fbsd``. If the
254 user is on the keyword in question, the news item should be displayed. 259 user is on the keyword in question, the news item should be displayed.
255 260
256``Display-If-Profile:`` 261``Display-If-Profile:``
257 A profile path, for example ``default-linux/sparc/sparc64/server``. If the 262 A profile path, for example ``default-linux/sparc/sparc64/server``. If the
258 user is using the exact profile in question, or a subprofile of this 263 user is using the exact profile in question, the news item should be
259 profile, the news item should be displayed. This header may be used to 264 displayed. This header may be used to replace ``deprecated`` files in the
260 replace ``deprecated`` files in the future. 265 future.
261 266
262.. Note:: When performing package moves, developers must also update any 267.. Note:: When performing package moves, developers must also update any
263 relevant ``Display-If-Installed`` headers in news files. 268 relevant ``Display-If-Installed`` headers in news files.
264 269
265The algorithm used to determine whether a news item is 'relevant' is as 270The algorithm used to determine whether a news item is 'relevant' is as
346 351
347.. Note:: A previous draft of this GLEP instead used the main ``gentoo-x86`` 352.. Note:: A previous draft of this GLEP instead used the main ``gentoo-x86``
348 tree. This was changed following advice from Infrastructure 353 tree. This was changed following advice from Infrastructure
349 [#ramereth-repo]_. Both solutions have the same end result. 354 [#ramereth-repo]_. Both solutions have the same end result.
350 355
351This repository will contain directories named ``yyyy/mm/``, where ``yyyy`` is 356This repository will contain directories named ``yyyy/``, where ``yyyy`` is
352the current year and ``mm`` is the current month number (01 for January through
35312 for December). This separation will help keep news items more manageable. 357the current year. This separation will help keep news items more manageable.
354 358
355The contents of this repository will automatically be merged with the main rsync 359The contents of this repository will automatically be merged with the main rsync
356tree, placing the items in a ``metadata/news/`` directory. The method used for 360tree, placing the items in a ``metadata/news/`` directory. The method used for
357merging these items and the frequency at which it will occur is beyond the scope 361merging these items and the frequency at which it will occur is beyond the scope
358of this GLEP; a similar setup is already used for merging GLSAs into the rsync 362of this GLEP; a similar setup is already used for merging GLSAs into the rsync
359tree. 363tree.
360 364
361The main rsync tree will **not** use the ``yyyy/mm/`` subdirectory layout. The 365The main rsync tree will **not** use the ``yyyy/`` subdirectory layout. The
362news item directories will all be immediately under the ``metadata/news/`` 366news item directories will all be immediately under the ``metadata/news/``
363directory. 367directory.
364 368
365Client Side 369Client Side
366''''''''''' 370'''''''''''
410 414
411Once a news item is marked for reading, third party tools (or traditional core 415Once a news item is marked for reading, third party tools (or traditional core
412Unix tools) can be used to display and view the news files. 416Unix tools) can be used to display and view the news files.
413 417
414When a news item is read, its name should be removed from the 418When a news item is read, its name should be removed from the
415``news-repoid.unread`` file. If a news client acts as an interactive reader 419``news-${repoid}.unread`` file. If a news client acts as an interactive reader
416rather than a gateway, it should then add the name to a ``news-repoid.read`` 420rather than a gateway, it should then add the name to a ``news-${repoid}.read``
417file in the same directory with the same file format. 421file in the same directory with the same file format.
418 422
419An ``eselect`` [#eselect]_ module shall be created as the 'suggested' display 423An ``eselect`` [#eselect]_ module shall be created as the 'suggested' display
420tool; other display tools (for example, a news to email forwarder, which would 424tool; other display tools (for example, a news to email forwarder, which would
421be ideal for users who sync on a ``cron``) are left as options for those who 425be ideal for users who sync on a ``cron``) are left as options for those who
445the ``news/`` directory. 449the ``news/`` directory.
446 450
447Reference Implementation 451Reference Implementation
448======================== 452========================
449 453
450Portage Code 454A reference implementation of the required package manager support can be found
451------------ 455in Paludis [#paludis]_, along with a reference newsreader implemented as an
452 456eselect module [#eselect-news]_.
453TODO
454
455Simple ``eselect`` News Client
456------------------------------
457
458TODO Removed until the exact format details are figured out.
459
460Simple News to Mail Forwarder
461-----------------------------
462
463TODO Removed until the exact format details are figured out.
464 457
465Credits 458Credits
466======= 459=======
467 460
468The idea behind notifying users of news updates via Portage comes from Stuart 461The idea behind notifying users of news updates via Portage comes from Stuart
474completely against their suggestions. 467completely against their suggestions.
475 468
476Example Files 469Example Files
477============= 470=============
478 471
479TODO Removed until the exact format details are figured out. 472`example-news-item.txt <glep-0042-extras/example-news-item.txt>`_
473 An example news item.
480 474
481References 475References
482========== 476==========
483 477
484.. [#bug-11359] Bugzilla Bug 11359 478.. [#bug-11359] Bugzilla Bug 11359
511 Albertson, 505 Albertson,
512 http://marc.theaimsgroup.com/?l=gentoo-dev&m=113111585907703&w=2 506 http://marc.theaimsgroup.com/?l=gentoo-dev&m=113111585907703&w=2
513.. [#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"
514.. [#rfc-3629] RFC 3629: "UTF-8, a transformation format of ISO 10646" 508.. [#rfc-3629] RFC 3629: "UTF-8, a transformation format of ISO 10646"
515 http://www.ietf.org/rfc/rfc3629.txt 509 http://www.ietf.org/rfc/rfc3629.txt
510.. [#paludis] Paludis homepage, http://paludis.berlios.de
511.. [#eselect-news] news.eselect, http://svn.berlios.de/svnroot/repos/paludis/trunk/eselect/news.eselect
516.. [#stuart-blog] "Favouring an automatic news mechanism", Stuart Herbert, 512.. [#stuart-blog] "Favouring an automatic news mechanism", Stuart Herbert,
517 http://stu.gnqs.org/diary/gentoo.php/2005/10/28/favouring_an_automatic_news_mechanism 513 http://stu.gnqs.org/diary/gentoo.php/2005/10/28/favouring_an_automatic_news_mechanism
518 514
519Copyright 515Copyright
520========= 516=========

Legend:
Removed from v.1.7  
changed lines
  Added in v.1.14

  ViewVC Help
Powered by ViewVC 1.1.20