/[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.6 Revision 1.12
1GLEP: 42 1GLEP: 42
2Title: Critical News Reporting 2Title: Critical News Reporting
3Version: $Revision: 1.6 $ 3Version: $Revision: 1.12 $
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: 2005/12/18 04:16:44 $ 7Last-Modified: $Date: 2006/09/05 20:36:38 $
6Status: Draft 8Status: Draft
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 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
139Required Portage Enhancements 141Required Portage Enhancements
140----------------------------- 142-----------------------------
141 143
142The following extensions to Portage are required: 144The following extensions to Portage are required:
143 145
144TODO: ferringb wants spaces added to the first item on the list. I don't,
145because it makes repo id -> filename mappings nasty.
146
147* Every repository (including overlays) will require a unique identifier. It is 146* Every repository (including overlays) will require a unique identifier. It is
148 assumed that an identifier will be a string consisting of characters from 147 assumed that an identifier will be a string consisting of characters from
149 ``a`` to ``z``, ``A`` to ``Z``, ``0`` to ``9``, ``+`` (plus), ``-`` (hyphen), 148 ``a`` to ``z``, ``A`` to ``Z``, ``0`` to ``9``, ``+`` (plus), ``-`` (hyphen)
150 ``:`` (colon) and ``_`` (underscore). 149 ``_`` (underscore).
151 150
152* Portage must provide a way for external programs to obtain a list of all 151* 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 152 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``). 153 the form of a ``portageq`` command (e.g. ``portageq get_repo_ids``).
155 154
159 158
160* Portage must extend ``portageq has_version`` to support restrictions to a 159* Portage must extend ``portageq has_version`` to support restrictions to a
161 given repository ID. 160 given repository ID.
162 161
163* Portage must extend ``portageq`` to implement a command which returns whether 162* 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 163 or not the profile used for a given repository ID is exactly the given profile
165 (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``).
166 166
167These extensions are assumed during the following specification. 167These extensions are assumed during the following specification.
168 168
169News Item Identities 169News Item Identities
170-------------------- 170--------------------
172Each news item will have a unique identifier. This identifier will be in the 172Each news item will have a unique identifier. This identifier will be in the
173form ``yyyy-mm-dd-short-name``, where ``yyyy`` is the year (e.g. ``2005``), 173form ``yyyy-mm-dd-short-name``, where ``yyyy`` is the year (e.g. ``2005``),
174``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
175(``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
176news item (e.g. ``yoursql-updates``), consisting only of the characters ``a-z``, 176news item (e.g. ``yoursql-updates``), consisting only of the characters ``a-z``,
177``0-9``, ``+`` (plus), ``:`` (colon), ``-`` (hyphen) and ``_`` (underscore). 177``0-9``, ``+`` (plus), ``-`` (hyphen) and ``_`` (underscore).
178 178
179News Item Directories 179News Item Directories
180--------------------- 180---------------------
181 181
182Each news item will be represented by a directory whose name is the same as the 182Each news item will be represented by a directory whose name is the same as the
184 184
185The 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
186contains 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.
187 187
188If 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``
189(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
190provided. 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
191This anglocentricity is justified by precedent [#glep-34]_. 191the English version of a news item is authoritative. This anglocentricity is
192justified by precedent [#glep-34]_.
192 193
193News Item Files 194News Item Files
194--------------- 195---------------
195 196
196A 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
197compatibility with and for the same reasons as existing Gentoo documentation 198compatibility with and for the same reasons as existing Gentoo documentation
198[#docs-policy]_ and the tree [#glep-31]_. 199[#docs-policy]_ and the tree [#glep-31]_.
199 200
200News items should be signed with a detached GPG signature: :: 201News items must be signed with a detached GPG signature.::
201 202
202 gpg --armour --detach-sign ????-??-??-*.??.txt 203 gpg --armour --detach-sign ????-??-??-*.??.txt
204
205This GLEP does not specify the type or strength of signature to be used, nor
206does it discuss how, if at all, a centralised keychain will be provided. These
207issues should be handled as part of the signing policy discussions.
203 208
204A news item file's content will consist of an RFC 822 style header [#rfc-822]_ 209A news item file's content will consist of an RFC 822 style header [#rfc-822]_
205followed by the main body of the message as plain text. This GLEP defines 210followed by the main body of the message as plain text. This GLEP defines
206various optional and mandatory headers. Future GLEPs may propose new headers — 211various optional and mandatory headers. Future GLEPs may propose new headers —
207tools handling these news items must ignore any unrecognised header. 212tools handling these news items must ignore any unrecognised header.
225``Content-Type:`` 230``Content-Type:``
226 Must be ``text/plain``. Mandatory. 231 Must be ``text/plain``. Mandatory.
227 232
228``Posted:`` 233``Posted:``
229 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
230 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.
231 237
232``Revision:`` 238``Revision:``
233 Initially 1. Incremented every time a non-trivial change is made. Changes 239 Initially 1. Should be incremented every time a change is made to the news
234 which require a re-read of the news item should instead use a new news item 240 item. Changes that require a re-read of the news item (i.e., most changes
241 that are not spelling or formatting related) should instead use a new news
235 file. Mandatory. 242 item. Mandatory.
236 243
237``News-Item-Format:`` 244``News-Item-Format:``
238 Must be ``1.0``. Future revisions to the format may increment the minor 245 Must be ``1.0``. Future revisions to the format may increment the minor
239 number for backwards-compatible changes, or the major number for major 246 number for backwards-compatible changes, or the major number for major
240 changes. 247 changes.
241 248
242The following headers are used for filtering: 249The following headers are used for filtering:
243 250
244``Display-If-Installed:`` 251``Display-If-Installed:``
245 A dependency atom or simple package name (for example, 252 A dependency atom (for example, ``<dev-lang/php-5_alpha`` or
246 ``<dev-lang/php-5_alpha`` or ``net-www/apache``). If the user has the 253 ``net-www/apache``). If the user has the package specified installed from
247 package specified installed from the repository from which the news item was 254 the repository from which the news item was obtained, the news item should
248 obtained, the news item should be displayed. 255 be displayed.
249 256
250``Display-If-Keyword:`` 257``Display-If-Keyword:``
251 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
252 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.
253 260
254``Display-If-Profile:`` 261``Display-If-Profile:``
255 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
256 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
257 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
258 replace ``deprecated`` files in the future. 265 future.
259 266
260.. Note:: When performing package moves, developers must also update any 267.. Note:: When performing package moves, developers must also update any
261 relevant ``Display-If-Installed`` headers in news files. 268 relevant ``Display-If-Installed`` headers in news files.
262 269
263The 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
292 299
293Hyperlinks may be used to refer to further information (for example, an upgrade 300Hyperlinks may be used to refer to further information (for example, an upgrade
294guide). However, the main body of the news item should be descriptive and not 301guide). However, the main body of the news item should be descriptive and not
295simply a "read this link" text. It is assumed that the user will have access to 302simply a "read this link" text. It is assumed that the user will have access to
296a web browser *somewhere*, but not necessarily on the box which is being 303a web browser *somewhere*, but not necessarily on the box which is being
297administrated — this will be the case on may servers and routers, for example. 304administrated — this will be the case on many servers and routers, for example.
298 305
299Example News Item 306Example News Item
300''''''''''''''''' 307'''''''''''''''''
301 308
302`This hypothetical news item`__ could be used for an upgrade to the 309`This hypothetical news item`__ could be used for an upgrade to the
317posted to the ``gentoo-dev`` mailing list and ``Cc:``\ed to ``pr@gentoo.org`` 324posted to the ``gentoo-dev`` mailing list and ``Cc:``\ed to ``pr@gentoo.org``
318(exceptions may be made in exceptional circumstances). Any complaints — for 325(exceptions may be made in exceptional circumstances). Any complaints — for
319example regarding wording, clarity or accuracy — **must** be addressed before 326example regarding wording, clarity or accuracy — **must** be addressed before
320the news item goes live. 327the news item goes live.
321 328
322.. Note:: A previous draft of this GLEP allowed news items to be sent to
323 ``gentoo-core`` instead of ``gentoo-dev``. It is possible that a situation
324 may arise where this will be necessary (for example, a security update which
325 must break backwards compatibility and which cannot be revealed to the public
326 before a given date).
327
328News items must only be for **important** changes that may cause serious upgrade 329News items must only be for **important** changes that may cause serious upgrade
329or compatibility problems. Ordinary upgrade messages and non-critical news items 330or compatibility problems. Ordinary upgrade messages and non-critical news items
330should remain in ``einfo`` notices. The importance of the message to its 331should remain in ``einfo`` notices. The importance of the message to its
331intended audience should be justified with the proposal. 332intended audience should be justified with the proposal.
332 333
356the current year and ``mm`` is the current month number (01 for January through 357the current year and ``mm`` is the current month number (01 for January through
35712 for December). This separation will help keep news items more manageable. 35812 for December). This separation will help keep news items more manageable.
358 359
359The contents of this repository will automatically be merged with the main rsync 360The contents of this repository will automatically be merged with the main rsync
360tree, placing the items in a ``metadata/news/`` directory. The method used for 361tree, placing the items in a ``metadata/news/`` directory. The method used for
361merging these items is beyond the scope of this GLEP — a similar setup is 362merging these items and the frequency at which it will occur is beyond the scope
362already used for merging GLSAs into the rsync tree. 363of this GLEP; a similar setup is already used for merging GLSAs into the rsync
364tree.
363 365
364The main rsync tree will **not** use the ``yyyy/mm/`` subdirectory layout. 366The main rsync tree will **not** use the ``yyyy/mm/`` subdirectory layout. The
367news item directories will all be immediately under the ``metadata/news/``
368directory.
365 369
366Client Side 370Client Side
367''''''''''' 371'''''''''''
368 372
369Whenever relevant unread news items are found, the package manager will create a 373Whenever relevant unread news items are found, the package manager will create a
370file named ``/var/lib/gentoo/news/news-repoid.unread`` (if it does not 374file named ``/var/lib/gentoo/news/news-${repoid}.unread`` (if it does not
371already exist) and append the news item identifier (eg 375already exist) and append the news item identifier (eg
372``2005-11-01-yoursql-updates``) on a new line. 376``2005-11-01-yoursql-updates``) on a new line.
377
378All news item related files should be root owned and in the ``portage`` group
379with the group write (and, for directories, execute) bits set. News files should
380be world readable.
373 381
374Notification that new relevant news items will be displayed via the 382Notification that new relevant news items will be displayed via the
375``emerge`` tool in a similar way to the existing "configuration files need 383``emerge`` tool in a similar way to the existing "configuration files need
376updating" messages: 384updating" messages:
377 385
383Checks for new news messages should be displayed: 391Checks for new news messages should be displayed:
384 392
385* After an ``emerge sync`` 393* After an ``emerge sync``
386* After an ``emerge --pretend`` 394* After an ``emerge --pretend``
387* Before an ``emerge <target>`` (which may also include a red warning message) 395* Before an ``emerge <target>`` (which may also include a red warning message)
388* Before an ``emerge --ask <target>`` sequence 396
397The package manager does not need to know how to launch the user's choice of
398news client. This is consistent with the way configuration file updates are
399handled.
389 400
390The package manager may use a timestamp check file to avoid having to process 401The package manager may use a timestamp check file to avoid having to process
391news items unnecessarily. 402news items unnecessarily.
392 403
393The package manager must keep track of news items that have already been added 404The package manager must keep track of news items that have already been added
394to the unread list to avoid repeatedly marking a deleted news item. This could 405to the unread list to avoid repeatedly marking a deleted news item. This could
395be handled via a ``news-repoid.skip`` file containing the IDs of news items that 406be handled via a ``news-${repoid}.skip`` file containing the IDs of news items
396have already been added to a ``news-repoid.unread`` file, but this method is not 407that have already been added to a ``news-${repoid}.unread`` file, but this
397required by this GLEP. 408method is not required by this GLEP.
398 409
399Users who really don't care about news items can use ``rsync_excludes`` to 410Users who really don't care about news items can use ``rsync_excludes`` to
400filter out the ``metadata/news/`` directory. 411filter out the ``metadata/news/`` directory.
401 412
402News Item Clients 413News Item Clients
404 415
405Once a news item is marked for reading, third party tools (or traditional core 416Once a news item is marked for reading, third party tools (or traditional core
406Unix tools) can be used to display and view the news files. 417Unix tools) can be used to display and view the news files.
407 418
408When a news item is read, its name should be removed from the 419When a news item is read, its name should be removed from the
409``news-repoid.unread`` file. If a news client acts as an interactive reader 420``news-${repoid}.unread`` file. If a news client acts as an interactive reader
410rather than a gateway, it should then add the name to a ``news-repoid.read`` 421rather than a gateway, it should then add the name to a ``news-${repoid}.read``
411file in the same directory with the same file format. 422file in the same directory with the same file format.
412 423
413An ``eselect`` [#eselect]_ module shall be created as the 'suggested' display 424An ``eselect`` [#eselect]_ module shall be created as the 'suggested' display
414tool; other display tools (for example, a news to email forwarder, which would 425tool; other display tools (for example, a news to email forwarder, which would
415be ideal for users who sync on a ``cron``) are left as options for those who 426be ideal for users who sync on a ``cron``) are left as options for those who
439the ``news/`` directory. 450the ``news/`` directory.
440 451
441Reference Implementation 452Reference Implementation
442======================== 453========================
443 454
444Portage Code 455A reference implementation of the required package manager support can be found
445------------ 456in Paludis [#paludis]_, along with a reference newsreader implemented as an
446 457eselect module [#eselect-news]_.
447TODO
448
449Simple ``eselect`` News Client
450------------------------------
451
452TODO Removed until the exact format details are figured out.
453
454Simple News to Mail Forwarder
455-----------------------------
456
457TODO Removed until the exact format details are figured out.
458 458
459Credits 459Credits
460======= 460=======
461 461
462The idea behind notifying users of news updates via Portage comes from Stuart 462The idea behind notifying users of news updates via Portage comes from Stuart
463Herbert [#stuart-blog]_. 463Herbert [#stuart-blog]_.
464 464
465Thanks to Lance Albertson, Stephen Bennett, Donnie Berkholz, Grant Goodyear, 465Thanks to Lance Albertson, Stephen Bennett, Donnie Berkholz, Grant Goodyear,
466Brian Harring, Dan Meltzer, Jason Stubbs, Paul de Vrieze and Alec Warner for 466Brian Harring, Marius Mauch, Dan Meltzer, Jason Stubbs, Paul de Vrieze and Alec
467input. Some of the ideas presented here are theirs, others go completely 467Warner for input. Some of the ideas presented here are theirs, others go
468against their suggestions. 468completely against their suggestions.
469 469
470Example Files 470Example Files
471============= 471=============
472 472
473TODO Removed until the exact format details are figured out. 473`example-news-item.txt <glep-0042-extras/example-news-item.txt>`_
474 An example news item.
474 475
475References 476References
476========== 477==========
477 478
478.. [#bug-11359] Bugzilla Bug 11359 479.. [#bug-11359] Bugzilla Bug 11359
505 Albertson, 506 Albertson,
506 http://marc.theaimsgroup.com/?l=gentoo-dev&m=113111585907703&w=2 507 http://marc.theaimsgroup.com/?l=gentoo-dev&m=113111585907703&w=2
507.. [#rfc-822] RFC 822 "Standard for the format of ARPA Internet text messages" 508.. [#rfc-822] RFC 822 "Standard for the format of ARPA Internet text messages"
508.. [#rfc-3629] RFC 3629: "UTF-8, a transformation format of ISO 10646" 509.. [#rfc-3629] RFC 3629: "UTF-8, a transformation format of ISO 10646"
509 http://www.ietf.org/rfc/rfc3629.txt 510 http://www.ietf.org/rfc/rfc3629.txt
511.. [#paludis] Paludis homepage, http://paludis.berlios.de
512.. [#eselect-news] news.eselect, http://svn.berlios.de/svnroot/repos/paludis/trunk/eselect/news.eselect
510.. [#stuart-blog] "Favouring an automatic news mechanism", Stuart Herbert, 513.. [#stuart-blog] "Favouring an automatic news mechanism", Stuart Herbert,
511 http://stu.gnqs.org/diary/gentoo.php/2005/10/28/favouring_an_automatic_news_mechanism 514 http://stu.gnqs.org/diary/gentoo.php/2005/10/28/favouring_an_automatic_news_mechanism
512 515
513Copyright 516Copyright
514========= 517=========

Legend:
Removed from v.1.6  
changed lines
  Added in v.1.12

  ViewVC Help
Powered by ViewVC 1.1.20