/[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.4 Revision 1.7
1GLEP: 42 1GLEP: 42
2Title: Critical News Reporting 2Title: Critical News Reporting
3Version: $Revision: 1.4 $ 3Version: $Revision: 1.7 $
4Author: Ciaran McCreesh <ciaranm@gentoo.org> 4Author: Ciaran McCreesh <ciaranm@gentoo.org>
5Last-Modified: $Date: 2005/12/11 01:38:18 $ 5Last-Modified: $Date: 2006/01/05 15:10:45 $
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 10Post-History: 1-Nov-2005, 5-Nov-2005, 7-Nov-2005, 11-Dec-2005, 13-Dec-2005, 18-Dec-2005, 5-Jan-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
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 during the upgrade process.
23Recent examples of the latter include the ``gcc-3.4`` stabilisation on ``x86`` 23Recent examples of the latter include the ``gcc-3.4`` stabilisation on ``x86``
24and the ``mysql-5`` database format changes. 24and the ``mysql-4.1`` database 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
30* The ``gentoo-announce``, ``gentoo-user`` and ``gentoo-dev`` mailing lists 30* The ``gentoo-announce``, ``gentoo-user`` and ``gentoo-dev`` mailing lists
31* The Gentoo Forums 31* The Gentoo Forums
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 35
35A 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
36to avoid repeats of the various recent upgrade debacles. This GLEP proposes a 37to avoid repeats of the various recent upgrade debacles. This GLEP proposes a
37solution 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.
38 39
133 informing the user that there are unread news items. 134 informing the user that there are unread news items.
134 135
1356. 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
136 Item Clients`_. 137 Item Clients`_.
137 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 matches a certain base path
162 (e.g. ``portageq profile_used default-linux/sparc/sparc64/2004.3 gentoo-x86``).
163
164These extensions are assumed during the following specification.
165
138News Item Identities 166News Item Identities
139-------------------- 167--------------------
140 168
141Each news item will have a unique identifier. This identifier will be in the 169Each news item will have a unique identifier. This identifier will be in the
142form ``yyyy-mm-dd-short-name``, where ``yyyy`` is the year (e.g. ``2005``), 170form ``yyyy-mm-dd-short-name``, where ``yyyy`` is the year (e.g. ``2005``),
143``mm`` is the month (``01`` through ``12``) and dd is the day of the month 171``mm`` is the month (``01`` through ``12``) and dd is the day of the month
144(``01`` through ``31``). The ``short-name`` is a very short name describing the 172(``01`` through ``31``). The ``short-name`` is a very short name describing the
145news item (e.g. ``yoursql-updates``), consisting only of the characters ``a-z``, 173news item (e.g. ``yoursql-updates``), consisting only of the characters ``a-z``,
146``0-9`` and ``-`` (hyphen). 174``0-9``, ``+`` (plus), ``-`` (hyphen) and ``_`` (underscore).
147 175
148News Item Directories 176News Item Directories
149--------------------- 177---------------------
150 178
151Each news item will be represented by a directory whose name is the same as the 179Each news item will be represented by a directory whose name is the same as the
164 192
165A news item file is a text file, encoded using UTF-8 [#rfc-3629]_ for 193A news item file is a text file, encoded using UTF-8 [#rfc-3629]_ for
166compatibility with and for the same reasons as existing Gentoo documentation 194compatibility with and for the same reasons as existing Gentoo documentation
167[#docs-policy]_ and the tree [#glep-31]_. 195[#docs-policy]_ and the tree [#glep-31]_.
168 196
169News items should be signed with a detached GPG signature: :: 197News items must be signed with a detached GPG signature.::
170 198
171 gpg --armour --detach-sign ????-??-??-*.??.txt 199 gpg --armour --detach-sign ????-??-??-*.??.txt
200
201This GLEP does not specify the type or strength of signature to be used, nor
202does it discuss how, if at all, a centralised keychain will be provided. These
203issues should be handled as part of the signing policy discussions.
172 204
173A news item file's content will consist of an RFC 822 style header [#rfc-822]_ 205A news item file's content will consist of an RFC 822 style header [#rfc-822]_
174followed by the main body of the message as plain text. This GLEP defines 206followed by the main body of the message as plain text. This GLEP defines
175various optional and mandatory headers. Future GLEPs may propose new headers — 207various optional and mandatory headers. Future GLEPs may propose new headers —
176tools handling these news items must ignore any unrecognised header. 208tools handling these news items must ignore any unrecognised header.
193 225
194``Content-Type:`` 226``Content-Type:``
195 Must be ``text/plain``. Mandatory. 227 Must be ``text/plain``. Mandatory.
196 228
197``Posted:`` 229``Posted:``
198 Date of posting, in ``dd-mmm-yyyy`` format (e.g. 14-Aug-2001) for 230 Date of posting, in ``yyyy-mm-dd`` format (e.g. 2005-12-18) for
199 compatibility with GLEP 1 [#glep-1]_. UTC time in ``hh-mm-ss +0000`` format 231 compatibility with GLEP 45 [#glep-45]_. Mandatory.
200 may also be included. Mandatory.
201 232
202``Revision:`` 233``Revision:``
203 Initially 1. Incremented every time a non-trivial change is made. Changes 234 Initially 1. Should be incremented every time a change is made to the news
204 which require a re-read of the news item should instead use a new news item 235 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
205 file. Mandatory. 237 item. Mandatory.
206 238
207``News-Item-Format:`` 239``News-Item-Format:``
208 Must be ``1.0``. Future revisions to the format may increment the minor 240 Must be ``1.0``. Future revisions to the format may increment the minor
209 number for backwards-compatible changes, or the major number for major 241 number for backwards-compatible changes, or the major number for major
210 changes. 242 changes.
211 243
212The following headers are used for filtering: 244The following headers are used for filtering:
213 245
214``Display-If-Installed:`` 246``Display-If-Installed:``
215 A dependency atom or simple package name (for example, 247 A dependency atom (for example, ``<dev-lang/php-5_alpha`` or
216 ``<dev-lang/php-5_alpha`` or ``net-www/apache``). If the user has the 248 ``net-www/apache``). If the user has the package specified installed from
217 package specified installed, the news item should be displayed. 249 the repository from which the news item was obtained, the news item should
250 be displayed.
218 251
219``Display-If-Keyword:`` 252``Display-If-Keyword:``
220 A keyword [#glep-22]_ name, for example ``mips`` or ``x86-fbsd``. If the 253 A keyword [#glep-22]_ name, for example ``mips`` or ``x86-fbsd``. If the
221 user is on the keyword in question, the news item should be displayed. 254 user is on the keyword in question, the news item should be displayed.
222 255
223``Display-If-Profile:`` 256``Display-If-Profile:``
224 A profile path, for example ``default-linux/sparc/sparc64/server``. Standard 257 A profile path, for example ``default-linux/sparc/sparc64/server``. If the
225 shell GLOB wildcards may be used. If the user is using the exact profile in 258 user is using the exact profile in question, or a subprofile of this
226 question, the news item should be displayed. This header may be used to 259 profile, the news item should be displayed. This header may be used to
227 replace ``deprecated`` files in the future. 260 replace ``deprecated`` files in the future.
228 261
229.. Note:: When performing package moves, developers must also update any 262.. Note:: When performing package moves, developers must also update any
230 relevant ``Display-If-Installed`` headers in news files. 263 relevant ``Display-If-Installed`` headers in news files.
231 264
261 294
262Hyperlinks may be used to refer to further information (for example, an upgrade 295Hyperlinks may be used to refer to further information (for example, an upgrade
263guide). However, the main body of the news item should be descriptive and not 296guide). However, the main body of the news item should be descriptive and not
264simply a "read this link" text. It is assumed that the user will have access to 297simply a "read this link" text. It is assumed that the user will have access to
265a web browser *somewhere*, but not necessarily on the box which is being 298a web browser *somewhere*, but not necessarily on the box which is being
266administrated — this will be the case on may servers and routers, for example. 299administrated — this will be the case on many servers and routers, for example.
267 300
268Example News Item 301Example News Item
269''''''''''''''''' 302'''''''''''''''''
270 303
271`This hypothetical news item`__ could be used for an upgrade to the 304`This hypothetical news item`__ could be used for an upgrade to the
286posted to the ``gentoo-dev`` mailing list and ``Cc:``\ed to ``pr@gentoo.org`` 319posted to the ``gentoo-dev`` mailing list and ``Cc:``\ed to ``pr@gentoo.org``
287(exceptions may be made in exceptional circumstances). Any complaints — for 320(exceptions may be made in exceptional circumstances). Any complaints — for
288example regarding wording, clarity or accuracy — **must** be addressed before 321example regarding wording, clarity or accuracy — **must** be addressed before
289the news item goes live. 322the news item goes live.
290 323
291.. Note:: A previous draft of this GLEP allowed news items to be sent to
292 ``gentoo-core`` instead of ``gentoo-dev``. It is possible that a situation
293 may arise where this will be necessary (for example, a security update which
294 must break backwards compatibility and which cannot be revealed to the public
295 before a given date).
296
297News items must only be for **important** changes that may cause serious upgrade 324News items must only be for **important** changes that may cause serious upgrade
298or compatibility problems. Ordinary upgrade messages and non-critical news items 325or compatibility problems. Ordinary upgrade messages and non-critical news items
299should remain in ``einfo`` notices. The importance of the message to its 326should remain in ``einfo`` notices. The importance of the message to its
300intended audience should be justified with the proposal. 327intended audience should be justified with the proposal.
301 328
325the current year and ``mm`` is the current month number (01 for January through 352the current year and ``mm`` is the current month number (01 for January through
32612 for December). This separation will help keep news items more manageable. 35312 for December). This separation will help keep news items more manageable.
327 354
328The contents of this repository will automatically be merged with the main rsync 355The contents of this repository will automatically be merged with the main rsync
329tree, placing the items in a ``metadata/news/`` directory. The method used for 356tree, placing the items in a ``metadata/news/`` directory. The method used for
330merging these items is beyond the scope of this GLEP — a similar setup is 357merging these items and the frequency at which it will occur is beyond the scope
331already used for merging GLSAs into the rsync tree. 358of this GLEP; a similar setup is already used for merging GLSAs into the rsync
359tree.
332 360
333The main rsync tree will **not** use the ``yyyy/mm/`` subdirectory layout. 361The main rsync tree will **not** use the ``yyyy/mm/`` subdirectory layout. The
362news item directories will all be immediately under the ``metadata/news/``
363directory.
334 364
335Client Side 365Client Side
336''''''''''' 366'''''''''''
337 367
338Whenever relevant unread news items are found, the package manager will create a 368Whenever relevant unread news items are found, the package manager will create a
339file named ``/var/lib/portage/news/news.unread`` (if it does not already exist) 369file named ``/var/lib/gentoo/news/news-${repoid}.unread`` (if it does not
340and append the news item identifier (eg ``2005-11-01-yoursql-updates``) on a new 370already exist) and append the news item identifier (eg
341line. 371``2005-11-01-yoursql-updates``) on a new line.
342 372
343.. Note:: Future changes to Portage involving support for multiple repositories 373All news item related files should be root owned and in the ``portage`` group
344 may require one news list per repository. Assuming repositories have some 374with the group write (and, for directories, execute) bits set. News files should
345 kind of unique identifier, this file could be named ``news-repoid.unread``. 375be world readable.
346 376
347Notification that new relevant news items will be displayed via the 377Notification that new relevant news items will be displayed via the
348``emerge`` tool in a similar way to the existing "configuration files need 378``emerge`` tool in a similar way to the existing "configuration files need
349updating" messages: 379updating" messages:
350 380
357 387
358* After an ``emerge sync`` 388* After an ``emerge sync``
359* After an ``emerge --pretend`` 389* After an ``emerge --pretend``
360* Before an ``emerge <target>`` (which may also include a red warning message) 390* Before an ``emerge <target>`` (which may also include a red warning message)
361 391
392The package manager does not need to know how to launch the user's choice of
393news client. This is consistent with the way configuration file updates are
394handled.
395
362The package manager may use a timestamp check file to avoid having to process 396The package manager may use a timestamp check file to avoid having to process
363news items unnecessarily. 397news items unnecessarily.
364 398
365The package manager must keep track of news items that have already been added 399The package manager must keep track of news items that have already been added
366to the unread list to avoid repeatedly marking a deleted news item. This could 400to the unread list to avoid repeatedly marking a deleted news item. This could
367be handled via a ``news.skip`` file, but implementation is not specified by this 401be handled via a ``news-${repoid}.skip`` file containing the IDs of news items
368GLEP. 402that have already been added to a ``news-${repoid}.unread`` file, but this
403method is not required by this GLEP.
369 404
370Users who really don't care about news items can use ``rsync_excludes`` to 405Users who really don't care about news items can use ``rsync_excludes`` to
371filter out the ``metadata/news/`` directory. 406filter out the ``metadata/news/`` directory.
372 407
373News Item Clients 408News Item Clients
374----------------- 409-----------------
375 410
376Once a news item is marked for reading, third party tools (or traditional core 411Once a news item is marked for reading, third party tools (or traditional core
377Unix tools) can be used to display and view the news files. 412Unix tools) can be used to display and view the news files.
378 413
379When a news item is read, its name should be removed from the ``news.unread`` 414When a news item is read, its name should be removed from the
380file. News clients may add the name to a ``news.read`` file in the same 415``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``
381directory with the same file format. 417file in the same directory with the same file format.
382 418
383An ``eselect`` [#eselect]_ module shall be created as the 'suggested' display 419An ``eselect`` [#eselect]_ module shall be created as the 'suggested' display
384tool; other display tools (for example, a news to email forwarder, which would 420tool; other display tools (for example, a news to email forwarder, which would
385be ideal for users who sync on a ``cron``) are left as options for those who 421be ideal for users who sync on a ``cron``) are left as options for those who
386desire them. 422desire them.
431 467
432The idea behind notifying users of news updates via Portage comes from Stuart 468The idea behind notifying users of news updates via Portage comes from Stuart
433Herbert [#stuart-blog]_. 469Herbert [#stuart-blog]_.
434 470
435Thanks to Lance Albertson, Stephen Bennett, Donnie Berkholz, Grant Goodyear, 471Thanks to Lance Albertson, Stephen Bennett, Donnie Berkholz, Grant Goodyear,
436Brian Harring, Dan Meltzer, Jason Stubbs, Paul de Vrieze and Alec Warner for 472Brian Harring, Marius Mauch, Dan Meltzer, Jason Stubbs, Paul de Vrieze and Alec
437input. Some of the ideas presented here are theirs, others go completely 473Warner for input. Some of the ideas presented here are theirs, others go
438against their suggestions. 474completely against their suggestions.
439 475
440Example Files 476Example Files
441============= 477=============
442 478
443TODO Removed until the exact format details are figured out. 479TODO Removed until the exact format details are figured out.
455 http://www.gentoo.org/proj/en/eselect/index.xml 491 http://www.gentoo.org/proj/en/eselect/index.xml
456.. [#forums-glsa] Forums user GLSA, 492.. [#forums-glsa] Forums user GLSA,
457 http://forums.gentoo.org/profile.php?mode=viewprofile&u=55648 493 http://forums.gentoo.org/profile.php?mode=viewprofile&u=55648
458.. [#forums-apache2] Forums thread "Gentoo Apache2 Config Change Idiocy", 494.. [#forums-apache2] Forums thread "Gentoo Apache2 Config Change Idiocy",
459 http://forums.gentoo.org/viewtopic-t-384368.html 495 http://forums.gentoo.org/viewtopic-t-384368.html
460.. [#glep-1] GLEP 1: "GLEP Purpose and Guidelines", Grant Goodyear,
461 http://www.gentoo.org/proj/en/glep/glep-0001.html
462.. [#glep-22] GLEP 22: "New "keyword" system to incorporate various 496.. [#glep-22] GLEP 22: "New "keyword" system to incorporate various
463 userlands/kernels/archs", Grant Goodyear, 497 userlands/kernels/archs", Grant Goodyear,
464 http://www.gentoo.org/proj/en/glep/glep-0022.html 498 http://www.gentoo.org/proj/en/glep/glep-0022.html
465.. [#glep-31] GLEP 31: "Character Sets for Portage Tree Items", Ciaran 499.. [#glep-31] GLEP 31: "Character Sets for Portage Tree Items", Ciaran
466 McCreesh, 500 McCreesh,
468.. [#glep-34] GLEP 34: "Per-Category metadata.xml Files", Ciaran McCreesh, 502.. [#glep-34] GLEP 34: "Per-Category metadata.xml Files", Ciaran McCreesh,
469 http://www.gentoo.org/proj/en/glep/glep-0034.html 503 http://www.gentoo.org/proj/en/glep/glep-0034.html
470.. [#glep-36] GLEP 36: "Subversion/CVS for Gentoo Hosted Projects", Aaron 504.. [#glep-36] GLEP 36: "Subversion/CVS for Gentoo Hosted Projects", Aaron
471 Walker, 505 Walker,
472 http://www.gentoo.org/proj/en/glep/glep-0036.html 506 http://www.gentoo.org/proj/en/glep/glep-0036.html
507.. [#glep-45] GLEP 45: "GLEP date format", Henrik Brix Andersen,
508 http://www.gentoo.org/proj/en/glep/glep-0045.html
473.. [#iso-639] ISO 639 "Code for the representation of names of languages" 509.. [#iso-639] ISO 639 "Code for the representation of names of languages"
474.. [#ramereth-repo] "Re: [gentoo-dev] GLEP ??: Critical News Reporting", Lance 510.. [#ramereth-repo] "Re: [gentoo-dev] GLEP ??: Critical News Reporting", Lance
475 Albertson, 511 Albertson,
476 http://marc.theaimsgroup.com/?l=gentoo-dev&m=113111585907703&w=2 512 http://marc.theaimsgroup.com/?l=gentoo-dev&m=113111585907703&w=2
477.. [#rfc-822] RFC 822 "Standard for the format of ARPA Internet text messages" 513.. [#rfc-822] RFC 822 "Standard for the format of ARPA Internet text messages"

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

  ViewVC Help
Powered by ViewVC 1.1.20