/[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.6
1GLEP: 42 1GLEP: 42
2Title: Critical News Reporting 2Title: Critical News Reporting
3Version: $Revision: 1.4 $ 3Version: $Revision: 1.6 $
4Author: Ciaran McCreesh <ciaranm@gentoo.org> 4Author: Ciaran McCreesh <ciaranm@gentoo.org>
5Last-Modified: $Date: 2005/12/11 01:38:18 $ 5Last-Modified: $Date: 2005/12/18 04:16:44 $
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
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
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
148 assumed that an identifier will be a string consisting of characters from
149 ``a`` to ``z``, ``A`` to ``Z``, ``0`` to ``9``, ``+`` (plus), ``-`` (hyphen),
150 ``:`` (colon) and ``_`` (underscore).
151
152* 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
154 the form of a ``portageq`` command (e.g. ``portageq get_repo_ids``).
155
156* Portage must provide a way for external programs to obtain the base path for
157 a repository with a given ID. It is assumed that this will be in the form of
158 a ``portageq`` command (e.g. ``portageq get_repo_root gentoo-x86``).
159
160* Portage must extend ``portageq has_version`` to support restrictions to a
161 given repository ID.
162
163* 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
165 (e.g. ``portageq profile_used default-linux/sparc/sparc64/2004.3 gentoo-x86``).
166
167These extensions are assumed during the following specification.
168
138News Item Identities 169News Item Identities
139-------------------- 170--------------------
140 171
141Each 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
142form ``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``),
143``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
144(``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
145news 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``,
146``0-9`` and ``-`` (hyphen). 177``0-9``, ``+`` (plus), ``:`` (colon), ``-`` (hyphen) and ``_`` (underscore).
147 178
148News Item Directories 179News Item Directories
149--------------------- 180---------------------
150 181
151Each 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
193 224
194``Content-Type:`` 225``Content-Type:``
195 Must be ``text/plain``. Mandatory. 226 Must be ``text/plain``. Mandatory.
196 227
197``Posted:`` 228``Posted:``
198 Date of posting, in ``dd-mmm-yyyy`` format (e.g. 14-Aug-2001) for 229 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 230 compatibility with GLEP 45 [#glep-45]_. Mandatory.
200 may also be included. Mandatory.
201 231
202``Revision:`` 232``Revision:``
203 Initially 1. Incremented every time a non-trivial change is made. Changes 233 Initially 1. Incremented every time a non-trivial change is made. Changes
204 which require a re-read of the news item should instead use a new news item 234 which require a re-read of the news item should instead use a new news item
205 file. Mandatory. 235 file. Mandatory.
212The following headers are used for filtering: 242The following headers are used for filtering:
213 243
214``Display-If-Installed:`` 244``Display-If-Installed:``
215 A dependency atom or simple package name (for example, 245 A dependency atom or simple package name (for example,
216 ``<dev-lang/php-5_alpha`` or ``net-www/apache``). If the user has the 246 ``<dev-lang/php-5_alpha`` or ``net-www/apache``). If the user has the
247 package specified installed from the repository from which the news item was
217 package specified installed, the news item should be displayed. 248 obtained, the news item should be displayed.
218 249
219``Display-If-Keyword:`` 250``Display-If-Keyword:``
220 A keyword [#glep-22]_ name, for example ``mips`` or ``x86-fbsd``. If the 251 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. 252 user is on the keyword in question, the news item should be displayed.
222 253
223``Display-If-Profile:`` 254``Display-If-Profile:``
224 A profile path, for example ``default-linux/sparc/sparc64/server``. Standard 255 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 256 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 257 profile, the news item should be displayed. This header may be used to
227 replace ``deprecated`` files in the future. 258 replace ``deprecated`` files in the future.
228 259
229.. Note:: When performing package moves, developers must also update any 260.. Note:: When performing package moves, developers must also update any
230 relevant ``Display-If-Installed`` headers in news files. 261 relevant ``Display-If-Installed`` headers in news files.
231 262
334 365
335Client Side 366Client Side
336''''''''''' 367'''''''''''
337 368
338Whenever relevant unread news items are found, the package manager will create a 369Whenever 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) 370file 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 371already exist) and append the news item identifier (eg
341line. 372``2005-11-01-yoursql-updates``) on a new line.
342
343.. Note:: Future changes to Portage involving support for multiple repositories
344 may require one news list per repository. Assuming repositories have some
345 kind of unique identifier, this file could be named ``news-repoid.unread``.
346 373
347Notification that new relevant news items will be displayed via the 374Notification that new relevant news items will be displayed via the
348``emerge`` tool in a similar way to the existing "configuration files need 375``emerge`` tool in a similar way to the existing "configuration files need
349updating" messages: 376updating" messages:
350 377
356Checks for new news messages should be displayed: 383Checks for new news messages should be displayed:
357 384
358* After an ``emerge sync`` 385* After an ``emerge sync``
359* After an ``emerge --pretend`` 386* After an ``emerge --pretend``
360* Before an ``emerge <target>`` (which may also include a red warning message) 387* Before an ``emerge <target>`` (which may also include a red warning message)
388* Before an ``emerge --ask <target>`` sequence
361 389
362The package manager may use a timestamp check file to avoid having to process 390The package manager may use a timestamp check file to avoid having to process
363news items unnecessarily. 391news items unnecessarily.
364 392
365The package manager must keep track of news items that have already been added 393The 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 394to 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 395be handled via a ``news-repoid.skip`` file containing the IDs of news items that
368GLEP. 396have already been added to a ``news-repoid.unread`` file, but this method is not
397required by this GLEP.
369 398
370Users who really don't care about news items can use ``rsync_excludes`` to 399Users who really don't care about news items can use ``rsync_excludes`` to
371filter out the ``metadata/news/`` directory. 400filter out the ``metadata/news/`` directory.
372 401
373News Item Clients 402News Item Clients
374----------------- 403-----------------
375 404
376Once a news item is marked for reading, third party tools (or traditional core 405Once 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. 406Unix tools) can be used to display and view the news files.
378 407
379When a news item is read, its name should be removed from the ``news.unread`` 408When 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 409``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``
381directory with the same file format. 411file in the same directory with the same file format.
382 412
383An ``eselect`` [#eselect]_ module shall be created as the 'suggested' display 413An ``eselect`` [#eselect]_ module shall be created as the 'suggested' display
384tool; other display tools (for example, a news to email forwarder, which would 414tool; 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 415be ideal for users who sync on a ``cron``) are left as options for those who
386desire them. 416desire them.
455 http://www.gentoo.org/proj/en/eselect/index.xml 485 http://www.gentoo.org/proj/en/eselect/index.xml
456.. [#forums-glsa] Forums user GLSA, 486.. [#forums-glsa] Forums user GLSA,
457 http://forums.gentoo.org/profile.php?mode=viewprofile&u=55648 487 http://forums.gentoo.org/profile.php?mode=viewprofile&u=55648
458.. [#forums-apache2] Forums thread "Gentoo Apache2 Config Change Idiocy", 488.. [#forums-apache2] Forums thread "Gentoo Apache2 Config Change Idiocy",
459 http://forums.gentoo.org/viewtopic-t-384368.html 489 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 490.. [#glep-22] GLEP 22: "New "keyword" system to incorporate various
463 userlands/kernels/archs", Grant Goodyear, 491 userlands/kernels/archs", Grant Goodyear,
464 http://www.gentoo.org/proj/en/glep/glep-0022.html 492 http://www.gentoo.org/proj/en/glep/glep-0022.html
465.. [#glep-31] GLEP 31: "Character Sets for Portage Tree Items", Ciaran 493.. [#glep-31] GLEP 31: "Character Sets for Portage Tree Items", Ciaran
466 McCreesh, 494 McCreesh,
468.. [#glep-34] GLEP 34: "Per-Category metadata.xml Files", Ciaran McCreesh, 496.. [#glep-34] GLEP 34: "Per-Category metadata.xml Files", Ciaran McCreesh,
469 http://www.gentoo.org/proj/en/glep/glep-0034.html 497 http://www.gentoo.org/proj/en/glep/glep-0034.html
470.. [#glep-36] GLEP 36: "Subversion/CVS for Gentoo Hosted Projects", Aaron 498.. [#glep-36] GLEP 36: "Subversion/CVS for Gentoo Hosted Projects", Aaron
471 Walker, 499 Walker,
472 http://www.gentoo.org/proj/en/glep/glep-0036.html 500 http://www.gentoo.org/proj/en/glep/glep-0036.html
501.. [#glep-45] GLEP 45: "GLEP date format", Henrik Brix Andersen,
502 http://www.gentoo.org/proj/en/glep/glep-0045.html
473.. [#iso-639] ISO 639 "Code for the representation of names of languages" 503.. [#iso-639] ISO 639 "Code for the representation of names of languages"
474.. [#ramereth-repo] "Re: [gentoo-dev] GLEP ??: Critical News Reporting", Lance 504.. [#ramereth-repo] "Re: [gentoo-dev] GLEP ??: Critical News Reporting", Lance
475 Albertson, 505 Albertson,
476 http://marc.theaimsgroup.com/?l=gentoo-dev&m=113111585907703&w=2 506 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" 507.. [#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.6

  ViewVC Help
Powered by ViewVC 1.1.20