/[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.5 Revision 1.9
1GLEP: 42 1GLEP: 42
2Title: Critical News Reporting 2Title: Critical News Reporting
3Version: $Revision: 1.5 $ 3Version: $Revision: 1.9 $
4Author: Ciaran McCreesh <ciaranm@gentoo.org> 4Author: Ciaran McCreesh <ciaranm@gentoo.org>
5Last-Modified: $Date: 2005/12/13 03:21:59 $ 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 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
134 informing the user that there are unread news items. 134 informing the user that there are unread news items.
135 135
1366. The news item is handled by the user's choice of news item reader. See `News 1366. The news item is handled by the user's choice of news item reader. See `News
137 Item Clients`_. 137 Item Clients`_.
138 138
139Required Portage Enhancements
140-----------------------------
141
142The following extensions to Portage are required:
143
144* Every repository (including overlays) will require a unique identifier. It is
145 assumed that an identifier will be a string consisting of characters from
146 ``a`` to ``z``, ``A`` to ``Z``, ``0`` to ``9``, ``+`` (plus), ``-`` (hyphen)
147 ``_`` (underscore).
148
149* Portage must provide a way for external programs to obtain a list of all
150 repository identifiers for a given system. It is assumed that this will be in
151 the form of a ``portageq`` command (e.g. ``portageq get_repo_ids``).
152
153* Portage must provide a way for external programs to obtain the base path for
154 a repository with a given ID. It is assumed that this will be in the form of
155 a ``portageq`` command (e.g. ``portageq get_repo_root gentoo-x86``).
156
157* Portage must extend ``portageq has_version`` to support restrictions to a
158 given repository ID.
159
160* Portage must extend ``portageq`` to implement a command which returns whether
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
163 gentoo-x86``).
164
165These extensions are assumed during the following specification.
166
139News Item Identities 167News Item Identities
140-------------------- 168--------------------
141 169
142Each news item will have a unique identifier. This identifier will be in the 170Each news item will have a unique identifier. This identifier will be in the
143form ``yyyy-mm-dd-short-name``, where ``yyyy`` is the year (e.g. ``2005``), 171form ``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 172``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 173(``01`` through ``31``). The ``short-name`` is a very short name describing the
146news item (e.g. ``yoursql-updates``), consisting only of the characters ``a-z``, 174news item (e.g. ``yoursql-updates``), consisting only of the characters ``a-z``,
147``0-9``, ``+`` (plus), ``:`` (colon) and ``-`` (hyphen). 175``0-9``, ``+`` (plus), ``-`` (hyphen) and ``_`` (underscore).
148 176
149News Item Directories 177News Item Directories
150--------------------- 178---------------------
151 179
152Each news item will be represented by a directory whose name is the same as the 180Each news item will be represented by a directory whose name is the same as the
154 182
155The 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
156contains 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.
157 185
158If 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``
159(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
160provided. 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
161This anglocentricity is justified by precedent [#glep-34]_. 189the English version of a news item is authoritative. This anglocentricity is
190justified by precedent [#glep-34]_.
162 191
163News Item Files 192News Item Files
164--------------- 193---------------
165 194
166A 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
167compatibility with and for the same reasons as existing Gentoo documentation 196compatibility with and for the same reasons as existing Gentoo documentation
168[#docs-policy]_ and the tree [#glep-31]_. 197[#docs-policy]_ and the tree [#glep-31]_.
169 198
170News items should be signed with a detached GPG signature: :: 199News items must be signed with a detached GPG signature.::
171 200
172 gpg --armour --detach-sign ????-??-??-*.??.txt 201 gpg --armour --detach-sign ????-??-??-*.??.txt
202
203This GLEP does not specify the type or strength of signature to be used, nor
204does it discuss how, if at all, a centralised keychain will be provided. These
205issues should be handled as part of the signing policy discussions.
173 206
174A news item file's content will consist of an RFC 822 style header [#rfc-822]_ 207A news item file's content will consist of an RFC 822 style header [#rfc-822]_
175followed by the main body of the message as plain text. This GLEP defines 208followed by the main body of the message as plain text. This GLEP defines
176various optional and mandatory headers. Future GLEPs may propose new headers — 209various optional and mandatory headers. Future GLEPs may propose new headers —
177tools handling these news items must ignore any unrecognised header. 210tools handling these news items must ignore any unrecognised header.
194 227
195``Content-Type:`` 228``Content-Type:``
196 Must be ``text/plain``. Mandatory. 229 Must be ``text/plain``. Mandatory.
197 230
198``Posted:`` 231``Posted:``
199 Date of posting, in ``dd-mmm-yyyy`` format (e.g. 14-Aug-2001) for 232 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 233 compatibility with GLEP 45 [#glep-45]_. Translations should use the date
201 may also be included. Mandatory. 234 of the original news item. Mandatory.
202 235
203``Revision:`` 236``Revision:``
204 Initially 1. Incremented every time a non-trivial change is made. Changes 237 Initially 1. Should be incremented every time a change is made to the news
205 which require a re-read of the news item should instead use a new news item 238 item. Changes that require a re-read of the news item (i.e., most changes
239 that are not spelling or formatting related) should instead use a new news
206 file. Mandatory. 240 item. Mandatory.
207 241
208``News-Item-Format:`` 242``News-Item-Format:``
209 Must be ``1.0``. Future revisions to the format may increment the minor 243 Must be ``1.0``. Future revisions to the format may increment the minor
210 number for backwards-compatible changes, or the major number for major 244 number for backwards-compatible changes, or the major number for major
211 changes. 245 changes.
212 246
213The following headers are used for filtering: 247The following headers are used for filtering:
214 248
215``Display-If-Installed:`` 249``Display-If-Installed:``
216 A dependency atom or simple package name (for example, 250 A dependency atom (for example, ``<dev-lang/php-5_alpha`` or
217 ``<dev-lang/php-5_alpha`` or ``net-www/apache``). If the user has the 251 ``net-www/apache``). If the user has the package specified installed from
218 package specified installed, the news item should be displayed. 252 the repository from which the news item was obtained, the news item should
253 be displayed.
219 254
220``Display-If-Keyword:`` 255``Display-If-Keyword:``
221 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
222 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.
223 258
224``Display-If-Profile:`` 259``Display-If-Profile:``
225 A profile path, for example ``default-linux/sparc/sparc64/server``. Standard 260 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 261 user is using the exact profile in question, the news item should be
227 question, 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
228 replace ``deprecated`` files in the future. 263 future.
229 264
230.. Note:: When performing package moves, developers must also update any 265.. Note:: When performing package moves, developers must also update any
231 relevant ``Display-If-Installed`` headers in news files. 266 relevant ``Display-If-Installed`` headers in news files.
232 267
233The 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
262 297
263Hyperlinks may be used to refer to further information (for example, an upgrade 298Hyperlinks may be used to refer to further information (for example, an upgrade
264guide). However, the main body of the news item should be descriptive and not 299guide). However, the main body of the news item should be descriptive and not
265simply a "read this link" text. It is assumed that the user will have access to 300simply a "read this link" text. It is assumed that the user will have access to
266a web browser *somewhere*, but not necessarily on the box which is being 301a web browser *somewhere*, but not necessarily on the box which is being
267administrated — this will be the case on may servers and routers, for example. 302administrated — this will be the case on many servers and routers, for example.
268 303
269Example News Item 304Example News Item
270''''''''''''''''' 305'''''''''''''''''
271 306
272`This hypothetical news item`__ could be used for an upgrade to the 307`This hypothetical news item`__ could be used for an upgrade to the
287posted to the ``gentoo-dev`` mailing list and ``Cc:``\ed to ``pr@gentoo.org`` 322posted to the ``gentoo-dev`` mailing list and ``Cc:``\ed to ``pr@gentoo.org``
288(exceptions may be made in exceptional circumstances). Any complaints — for 323(exceptions may be made in exceptional circumstances). Any complaints — for
289example regarding wording, clarity or accuracy — **must** be addressed before 324example regarding wording, clarity or accuracy — **must** be addressed before
290the news item goes live. 325the news item goes live.
291 326
292.. Note:: A previous draft of this GLEP allowed news items to be sent to
293 ``gentoo-core`` instead of ``gentoo-dev``. It is possible that a situation
294 may arise where this will be necessary (for example, a security update which
295 must break backwards compatibility and which cannot be revealed to the public
296 before a given date).
297
298News items must only be for **important** changes that may cause serious upgrade 327News items must only be for **important** changes that may cause serious upgrade
299or compatibility problems. Ordinary upgrade messages and non-critical news items 328or compatibility problems. Ordinary upgrade messages and non-critical news items
300should remain in ``einfo`` notices. The importance of the message to its 329should remain in ``einfo`` notices. The importance of the message to its
301intended audience should be justified with the proposal. 330intended audience should be justified with the proposal.
302 331
326the current year and ``mm`` is the current month number (01 for January through 355the current year and ``mm`` is the current month number (01 for January through
32712 for December). This separation will help keep news items more manageable. 35612 for December). This separation will help keep news items more manageable.
328 357
329The contents of this repository will automatically be merged with the main rsync 358The contents of this repository will automatically be merged with the main rsync
330tree, placing the items in a ``metadata/news/`` directory. The method used for 359tree, placing the items in a ``metadata/news/`` directory. The method used for
331merging these items is beyond the scope of this GLEP — a similar setup is 360merging these items and the frequency at which it will occur is beyond the scope
332already used for merging GLSAs into the rsync tree. 361of this GLEP; a similar setup is already used for merging GLSAs into the rsync
362tree.
333 363
334The main rsync tree will **not** use the ``yyyy/mm/`` subdirectory layout. 364The main rsync tree will **not** use the ``yyyy/mm/`` subdirectory layout. The
365news item directories will all be immediately under the ``metadata/news/``
366directory.
335 367
336Client Side 368Client Side
337''''''''''' 369'''''''''''
338 370
339Whenever relevant unread news items are found, the package manager will create a 371Whenever relevant unread news items are found, the package manager will create a
340file named ``/var/lib/gentoo/news/news-magic-chicken.unread`` (if it does not 372file named ``/var/lib/gentoo/news/news-${repoid}.unread`` (if it does not
341already exist) and append the news item identifier (eg 373already exist) and append the news item identifier (eg
342``2005-11-01-yoursql-updates``) on a new line. 374``2005-11-01-yoursql-updates``) on a new line.
343 375
344.. Note:: Future changes to Portage involving support for multiple repositories 376All news item related files should be root owned and in the ``portage`` group
345 may introduce repository names. In this case, the ``magic-chicken`` part of the 377with the group write (and, for directories, execute) bits set. News files should
346 filename should be replaced by a string representation of the repository 378be world readable.
347 name. Thus, news item clients should use a wildcard rather than hardcoding
348 the ``magic-chicken`` string.
349 379
350Notification that new relevant news items will be displayed via the 380Notification that new relevant news items will be displayed via the
351``emerge`` tool in a similar way to the existing "configuration files need 381``emerge`` tool in a similar way to the existing "configuration files need
352updating" messages: 382updating" messages:
353 383
359Checks for new news messages should be displayed: 389Checks for new news messages should be displayed:
360 390
361* After an ``emerge sync`` 391* After an ``emerge sync``
362* After an ``emerge --pretend`` 392* After an ``emerge --pretend``
363* Before an ``emerge <target>`` (which may also include a red warning message) 393* Before an ``emerge <target>`` (which may also include a red warning message)
364* Before an ``emerge --ask <target>`` sequence 394
395The package manager does not need to know how to launch the user's choice of
396news client. This is consistent with the way configuration file updates are
397handled.
365 398
366The package manager may use a timestamp check file to avoid having to process 399The package manager may use a timestamp check file to avoid having to process
367news items unnecessarily. 400news items unnecessarily.
368 401
369The package manager must keep track of news items that have already been added 402The package manager must keep track of news items that have already been added
370to the unread list to avoid repeatedly marking a deleted news item. This could 403to the unread list to avoid repeatedly marking a deleted news item. This could
371be handled via a ``news-magic-chicken.skip`` file, but implementation is not 404be handled via a ``news-${repoid}.skip`` file containing the IDs of news items
372specified by this GLEP. 405that have already been added to a ``news-${repoid}.unread`` file, but this
406method is not required by this GLEP.
373 407
374Users who really don't care about news items can use ``rsync_excludes`` to 408Users who really don't care about news items can use ``rsync_excludes`` to
375filter out the ``metadata/news/`` directory. 409filter out the ``metadata/news/`` directory.
376 410
377News Item Clients 411News Item Clients
379 413
380Once 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
381Unix tools) can be used to display and view the news files. 415Unix tools) can be used to display and view the news files.
382 416
383When 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
384``news-magic-chicken.unread`` file. If a news client acts as an interactive 418``news-${repoid}.unread`` file. If a news client acts as an interactive reader
385reader rather than a gateway, it should then add the name to a 419rather 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 420file in the same directory with the same file format.
387format (again, ``magic-chicken`` should be a wildcard rather than hardcoded).
388 421
389An ``eselect`` [#eselect]_ module shall be created as the 'suggested' display 422An ``eselect`` [#eselect]_ module shall be created as the 'suggested' display
390tool; 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
391be 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
392desire them. 425desire them.
415the ``news/`` directory. 448the ``news/`` directory.
416 449
417Reference Implementation 450Reference Implementation
418======================== 451========================
419 452
420Portage Code
421------------
422
423TODO 453TODO
424
425Simple ``eselect`` News Client
426------------------------------
427
428TODO Removed until the exact format details are figured out.
429
430Simple News to Mail Forwarder
431-----------------------------
432
433TODO Removed until the exact format details are figured out.
434 454
435Credits 455Credits
436======= 456=======
437 457
438The 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
439Herbert [#stuart-blog]_. 459Herbert [#stuart-blog]_.
440 460
441Thanks to Lance Albertson, Stephen Bennett, Donnie Berkholz, Grant Goodyear, 461Thanks to Lance Albertson, Stephen Bennett, Donnie Berkholz, Grant Goodyear,
442Brian Harring, Dan Meltzer, Jason Stubbs, Paul de Vrieze and Alec Warner for 462Brian Harring, Marius Mauch, Dan Meltzer, Jason Stubbs, Paul de Vrieze and Alec
443input. Some of the ideas presented here are theirs, others go completely 463Warner for input. Some of the ideas presented here are theirs, others go
444against their suggestions. 464completely against their suggestions.
445 465
446Example Files 466Example Files
447============= 467=============
448 468
449TODO 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.
450 471
451References 472References
452========== 473==========
453 474
454.. [#bug-11359] Bugzilla Bug 11359 475.. [#bug-11359] Bugzilla Bug 11359
461 http://www.gentoo.org/proj/en/eselect/index.xml 482 http://www.gentoo.org/proj/en/eselect/index.xml
462.. [#forums-glsa] Forums user GLSA, 483.. [#forums-glsa] Forums user GLSA,
463 http://forums.gentoo.org/profile.php?mode=viewprofile&u=55648 484 http://forums.gentoo.org/profile.php?mode=viewprofile&u=55648
464.. [#forums-apache2] Forums thread "Gentoo Apache2 Config Change Idiocy", 485.. [#forums-apache2] Forums thread "Gentoo Apache2 Config Change Idiocy",
465 http://forums.gentoo.org/viewtopic-t-384368.html 486 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 487.. [#glep-22] GLEP 22: "New "keyword" system to incorporate various
469 userlands/kernels/archs", Grant Goodyear, 488 userlands/kernels/archs", Grant Goodyear,
470 http://www.gentoo.org/proj/en/glep/glep-0022.html 489 http://www.gentoo.org/proj/en/glep/glep-0022.html
471.. [#glep-31] GLEP 31: "Character Sets for Portage Tree Items", Ciaran 490.. [#glep-31] GLEP 31: "Character Sets for Portage Tree Items", Ciaran
472 McCreesh, 491 McCreesh,
474.. [#glep-34] GLEP 34: "Per-Category metadata.xml Files", Ciaran McCreesh, 493.. [#glep-34] GLEP 34: "Per-Category metadata.xml Files", Ciaran McCreesh,
475 http://www.gentoo.org/proj/en/glep/glep-0034.html 494 http://www.gentoo.org/proj/en/glep/glep-0034.html
476.. [#glep-36] GLEP 36: "Subversion/CVS for Gentoo Hosted Projects", Aaron 495.. [#glep-36] GLEP 36: "Subversion/CVS for Gentoo Hosted Projects", Aaron
477 Walker, 496 Walker,
478 http://www.gentoo.org/proj/en/glep/glep-0036.html 497 http://www.gentoo.org/proj/en/glep/glep-0036.html
498.. [#glep-45] GLEP 45: "GLEP date format", Henrik Brix Andersen,
499 http://www.gentoo.org/proj/en/glep/glep-0045.html
479.. [#iso-639] ISO 639 "Code for the representation of names of languages" 500.. [#iso-639] ISO 639 "Code for the representation of names of languages"
480.. [#ramereth-repo] "Re: [gentoo-dev] GLEP ??: Critical News Reporting", Lance 501.. [#ramereth-repo] "Re: [gentoo-dev] GLEP ??: Critical News Reporting", Lance
481 Albertson, 502 Albertson,
482 http://marc.theaimsgroup.com/?l=gentoo-dev&m=113111585907703&w=2 503 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" 504.. [#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.9

  ViewVC Help
Powered by ViewVC 1.1.20