/[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.9
1GLEP: 42 1GLEP: 42
2Title: Critical News Reporting 2Title: Critical News Reporting
3Version: $Revision: 1.7 $ 3Version: $Revision: 1.9 $
4Author: Ciaran McCreesh <ciaranm@gentoo.org> 4Author: Ciaran McCreesh <ciaranm@gentoo.org>
5Last-Modified: $Date: 2006/01/05 15:10:45 $ 5Last-Modified: $Date: 2006/03/06 03:12:08 $
6Status: Draft 6Status: Draft
7Type: Standards Track 7Type: Standards Track
8Content-Type: text/x-rst 8Content-Type: text/x-rst
9Created: 31-Oct-2005 9Created: 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 10Post-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
11 11
12Abstract 12Abstract
13======== 13========
14 14
15This GLEP proposes a new way of informing users about important updates and news 15This GLEP proposes a new way of informing users about important updates and news
16regarding tree-related items. 16related to the tree.
17 17
18Motivation 18Motivation
19========== 19==========
20 20
21Although most package updates are clean and require little user action, 21Although most package updates are clean and require little user action,
22occasionally an upgrade requires user intervention during the upgrade process. 22occasionally an upgrade requires user intervention. Recent examples of the
23Recent examples of the latter include the ``gcc-3.4`` stabilisation on ``x86`` 23latter include the ``gcc-3.4`` stabilisation on ``x86`` and the ``mysql-4.1``
24and the ``mysql-4.1`` database format changes. 24database format changes.
25 25
26There are currently several ways of delivering important news items to our 26There are currently several ways of delivering important news items to our
27users, none of them particularly effective: 27users, none of them particularly effective:
28 28
29* Gentoo Weekly News 29* Gentoo Weekly News
32* The main Gentoo website 32* The main Gentoo website
33* RSS feeds of Gentoo news 33* RSS feeds of Gentoo news
34* ``einfo`` and ``ewarn`` messages in ``pkg_setup`` or ``pkg_postinst`` 34* ``einfo`` and ``ewarn`` messages in ``pkg_setup`` or ``pkg_postinst``
35 35
36A more reliable way of getting news of critical updates out to users is required 36A 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 37to 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. 38solution based around pushing news items out to the user via the ``rsync`` tree.
39 39
40.. Important:: This GLEP does not seek to replace or modify ``einfo`` messages 40.. 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 41 which are displayed post-install. That is a separate issue which is handled
42 by ``elog`` [#bug-11359]_. 42 by ``elog`` [#bug-11359]_.
52 given ample warning to plan difficult upgrades and changes, rather than only 52 given ample warning to plan difficult upgrades and changes, rather than only
53 being told just before action is necessary. 53 being told just before action is necessary.
54 54
55No user subscription required 55No user subscription required
56 It has already been demonstrated [#forums-apache2]_ that many users do not 56 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 57 read the ``gentoo-announce`` mailing list or ``RSS`` feeds. A solution that
58 requires subscription has no advantage over current methods. 58 requires subscription has no advantage over current methods.
59 59
60No user monitoring required 60No user monitoring required
61 It has already been demonstrated [#forums-apache2]_ that many users do not 61 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 62 read news items posted to the Gentoo website, or do not read news items
156 156
157* Portage must extend ``portageq has_version`` to support restrictions to a 157* Portage must extend ``portageq has_version`` to support restrictions to a
158 given repository ID. 158 given repository ID.
159 159
160* Portage must extend ``portageq`` to implement a command which returns whether 160* 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 161 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``). 162 (e.g. ``portageq profile_used default-linux/sparc/sparc64/2004.3
163 gentoo-x86``).
163 164
164These extensions are assumed during the following specification. 165These extensions are assumed during the following specification.
165 166
166News Item Identities 167News Item Identities
167-------------------- 168--------------------
181 182
182The directory will contain a file named ``yyyy-mm-dd-short-name.en.txt``, which 183The 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. 184contains the text of the news item, in English, in the format described below.
184 185
185If a news item is translated, other files named ``yyyy-mm-dd-short-name.xx.txt`` 186If 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 187(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. 188remains the same as the original news item) will also be provided. However, only
188This anglocentricity is justified by precedent [#glep-34]_. 189the English version of a news item is authoritative. This anglocentricity is
190justified by precedent [#glep-34]_.
189 191
190News Item Files 192News Item Files
191--------------- 193---------------
192 194
193A news item file is a text file, encoded using UTF-8 [#rfc-3629]_ for 195A news item file is a text file, encoded using UTF-8 [#rfc-3629]_ for
226``Content-Type:`` 228``Content-Type:``
227 Must be ``text/plain``. Mandatory. 229 Must be ``text/plain``. Mandatory.
228 230
229``Posted:`` 231``Posted:``
230 Date of posting, in ``yyyy-mm-dd`` format (e.g. 2005-12-18) for 232 Date of posting, in ``yyyy-mm-dd`` format (e.g. 2005-12-18) for
231 compatibility with GLEP 45 [#glep-45]_. Mandatory. 233 compatibility with GLEP 45 [#glep-45]_. Translations should use the date
234 of the original news item. Mandatory.
232 235
233``Revision:`` 236``Revision:``
234 Initially 1. Should be incremented every time a change is made to the news 237 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 238 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 239 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 256 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. 257 user is on the keyword in question, the news item should be displayed.
255 258
256``Display-If-Profile:`` 259``Display-If-Profile:``
257 A profile path, for example ``default-linux/sparc/sparc64/server``. If the 260 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 261 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 262 displayed. This header may be used to replace ``deprecated`` files in the
260 replace ``deprecated`` files in the future. 263 future.
261 264
262.. Note:: When performing package moves, developers must also update any 265.. Note:: When performing package moves, developers must also update any
263 relevant ``Display-If-Installed`` headers in news files. 266 relevant ``Display-If-Installed`` headers in news files.
264 267
265The algorithm used to determine whether a news item is 'relevant' is as 268The algorithm used to determine whether a news item is 'relevant' is as
410 413
411Once a news item is marked for reading, third party tools (or traditional core 414Once 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. 415Unix tools) can be used to display and view the news files.
413 416
414When a news item is read, its name should be removed from the 417When 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 418``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`` 419rather than a gateway, it should then add the name to a ``news-${repoid}.read``
417file in the same directory with the same file format. 420file in the same directory with the same file format.
418 421
419An ``eselect`` [#eselect]_ module shall be created as the 'suggested' display 422An ``eselect`` [#eselect]_ module shall be created as the 'suggested' display
420tool; other display tools (for example, a news to email forwarder, which would 423tool; 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 424be ideal for users who sync on a ``cron``) are left as options for those who
445the ``news/`` directory. 448the ``news/`` directory.
446 449
447Reference Implementation 450Reference Implementation
448======================== 451========================
449 452
450Portage Code
451------------
452
453TODO 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 454
465Credits 455Credits
466======= 456=======
467 457
468The idea behind notifying users of news updates via Portage comes from Stuart 458The idea behind notifying users of news updates via Portage comes from Stuart
474completely against their suggestions. 464completely against their suggestions.
475 465
476Example Files 466Example Files
477============= 467=============
478 468
479TODO Removed until the exact format details are figured out. 469`example-news-item.txt <glep-0042-extras/example-news-item.txt>`_
470 An example news item.
480 471
481References 472References
482========== 473==========
483 474
484.. [#bug-11359] Bugzilla Bug 11359 475.. [#bug-11359] Bugzilla Bug 11359

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

  ViewVC Help
Powered by ViewVC 1.1.20