/[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.7
1GLEP: 42 1GLEP: 42
2Title: Critical News Reporting 2Title: Critical News Reporting
3Version: $Revision: 1.6 $ 3Version: $Revision: 1.7 $
4Author: Ciaran McCreesh <ciaranm@gentoo.org> 4Author: Ciaran McCreesh <ciaranm@gentoo.org>
5Last-Modified: $Date: 2005/12/18 04:16:44 $ 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, 13-Dec-2005, 18-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
139Required Portage Enhancements 139Required Portage Enhancements
140----------------------------- 140-----------------------------
141 141
142The following extensions to Portage are required: 142The following extensions to Portage are required:
143 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 144* Every repository (including overlays) will require a unique identifier. It is
148 assumed that an identifier will be a string consisting of characters from 145 assumed that an identifier will be a string consisting of characters from
149 ``a`` to ``z``, ``A`` to ``Z``, ``0`` to ``9``, ``+`` (plus), ``-`` (hyphen), 146 ``a`` to ``z``, ``A`` to ``Z``, ``0`` to ``9``, ``+`` (plus), ``-`` (hyphen)
150 ``:`` (colon) and ``_`` (underscore). 147 ``_`` (underscore).
151 148
152* Portage must provide a way for external programs to obtain a list of all 149* 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 150 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``). 151 the form of a ``portageq`` command (e.g. ``portageq get_repo_ids``).
155 152
172Each 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
173form ``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``),
174``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
175(``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
176news 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``,
177``0-9``, ``+`` (plus), ``:`` (colon), ``-`` (hyphen) and ``_`` (underscore). 174``0-9``, ``+`` (plus), ``-`` (hyphen) and ``_`` (underscore).
178 175
179News Item Directories 176News Item Directories
180--------------------- 177---------------------
181 178
182Each 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
195 192
196A 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
197compatibility with and for the same reasons as existing Gentoo documentation 194compatibility with and for the same reasons as existing Gentoo documentation
198[#docs-policy]_ and the tree [#glep-31]_. 195[#docs-policy]_ and the tree [#glep-31]_.
199 196
200News items should be signed with a detached GPG signature: :: 197News items must be signed with a detached GPG signature.::
201 198
202 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.
203 204
204A 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]_
205followed 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
206various optional and mandatory headers. Future GLEPs may propose new headers — 207various optional and mandatory headers. Future GLEPs may propose new headers —
207tools handling these news items must ignore any unrecognised header. 208tools handling these news items must ignore any unrecognised header.
228``Posted:`` 229``Posted:``
229 Date of posting, in ``yyyy-mm-dd`` format (e.g. 2005-12-18) for 230 Date of posting, in ``yyyy-mm-dd`` format (e.g. 2005-12-18) for
230 compatibility with GLEP 45 [#glep-45]_. Mandatory. 231 compatibility with GLEP 45 [#glep-45]_. Mandatory.
231 232
232``Revision:`` 233``Revision:``
233 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
234 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
235 file. Mandatory. 237 item. Mandatory.
236 238
237``News-Item-Format:`` 239``News-Item-Format:``
238 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
239 number for backwards-compatible changes, or the major number for major 241 number for backwards-compatible changes, or the major number for major
240 changes. 242 changes.
241 243
242The following headers are used for filtering: 244The following headers are used for filtering:
243 245
244``Display-If-Installed:`` 246``Display-If-Installed:``
245 A dependency atom or simple package name (for example, 247 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 248 ``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 249 the repository from which the news item was obtained, the news item should
248 obtained, the news item should be displayed. 250 be displayed.
249 251
250``Display-If-Keyword:`` 252``Display-If-Keyword:``
251 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
252 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.
253 255
292 294
293Hyperlinks 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
294guide). 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
295simply 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
296a 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
297administrated — 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.
298 300
299Example News Item 301Example News Item
300''''''''''''''''' 302'''''''''''''''''
301 303
302`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
317posted 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``
318(exceptions may be made in exceptional circumstances). Any complaints — for 320(exceptions may be made in exceptional circumstances). Any complaints — for
319example regarding wording, clarity or accuracy — **must** be addressed before 321example regarding wording, clarity or accuracy — **must** be addressed before
320the news item goes live. 322the news item goes live.
321 323
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 324News items must only be for **important** changes that may cause serious upgrade
329or compatibility problems. Ordinary upgrade messages and non-critical news items 325or compatibility problems. Ordinary upgrade messages and non-critical news items
330should remain in ``einfo`` notices. The importance of the message to its 326should remain in ``einfo`` notices. The importance of the message to its
331intended audience should be justified with the proposal. 327intended audience should be justified with the proposal.
332 328
356the 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
35712 for December). This separation will help keep news items more manageable. 35312 for December). This separation will help keep news items more manageable.
358 354
359The 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
360tree, 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
361merging 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
362already used for merging GLSAs into the rsync tree. 358of this GLEP; a similar setup is already used for merging GLSAs into the rsync
359tree.
363 360
364The 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.
365 364
366Client Side 365Client Side
367''''''''''' 366'''''''''''
368 367
369Whenever 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
370file named ``/var/lib/gentoo/news/news-repoid.unread`` (if it does not 369file named ``/var/lib/gentoo/news/news-${repoid}.unread`` (if it does not
371already exist) and append the news item identifier (eg 370already exist) and append the news item identifier (eg
372``2005-11-01-yoursql-updates``) on a new line. 371``2005-11-01-yoursql-updates``) on a new line.
372
373All news item related files should be root owned and in the ``portage`` group
374with the group write (and, for directories, execute) bits set. News files should
375be world readable.
373 376
374Notification that new relevant news items will be displayed via the 377Notification that new relevant news items will be displayed via the
375``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
376updating" messages: 379updating" messages:
377 380
383Checks for new news messages should be displayed: 386Checks for new news messages should be displayed:
384 387
385* After an ``emerge sync`` 388* After an ``emerge sync``
386* After an ``emerge --pretend`` 389* After an ``emerge --pretend``
387* 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)
388* Before an ``emerge --ask <target>`` sequence 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.
389 395
390The 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
391news items unnecessarily. 397news items unnecessarily.
392 398
393The 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
394to 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
395be handled via a ``news-repoid.skip`` file containing the IDs of news items that 401be 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 402that have already been added to a ``news-${repoid}.unread`` file, but this
397required by this GLEP. 403method is not required by this GLEP.
398 404
399Users 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
400filter out the ``metadata/news/`` directory. 406filter out the ``metadata/news/`` directory.
401 407
402News Item Clients 408News Item Clients
461 467
462The 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
463Herbert [#stuart-blog]_. 469Herbert [#stuart-blog]_.
464 470
465Thanks to Lance Albertson, Stephen Bennett, Donnie Berkholz, Grant Goodyear, 471Thanks to Lance Albertson, Stephen Bennett, Donnie Berkholz, Grant Goodyear,
466Brian 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
467input. Some of the ideas presented here are theirs, others go completely 473Warner for input. Some of the ideas presented here are theirs, others go
468against their suggestions. 474completely against their suggestions.
469 475
470Example Files 476Example Files
471============= 477=============
472 478
473TODO Removed until the exact format details are figured out. 479TODO Removed until the exact format details are figured out.

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

  ViewVC Help
Powered by ViewVC 1.1.20