/[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.7
1GLEP: 42 1GLEP: 42
2Title: Critical News Reporting 2Title: Critical News Reporting
3Version: $Revision: 1.5 $ 3Version: $Revision: 1.7 $
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/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 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
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 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
139News Item Identities 166News Item Identities
140-------------------- 167--------------------
141 168
142Each 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
143form ``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``),
144``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
145(``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
146news 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``,
147``0-9``, ``+`` (plus), ``:`` (colon) and ``-`` (hyphen). 174``0-9``, ``+`` (plus), ``-`` (hyphen) and ``_`` (underscore).
148 175
149News Item Directories 176News Item Directories
150--------------------- 177---------------------
151 178
152Each 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
165 192
166A 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
167compatibility with and for the same reasons as existing Gentoo documentation 194compatibility with and for the same reasons as existing Gentoo documentation
168[#docs-policy]_ and the tree [#glep-31]_. 195[#docs-policy]_ and the tree [#glep-31]_.
169 196
170News items should be signed with a detached GPG signature: :: 197News items must be signed with a detached GPG signature.::
171 198
172 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.
173 204
174A 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]_
175followed 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
176various optional and mandatory headers. Future GLEPs may propose new headers — 207various optional and mandatory headers. Future GLEPs may propose new headers —
177tools handling these news items must ignore any unrecognised header. 208tools handling these news items must ignore any unrecognised header.
194 225
195``Content-Type:`` 226``Content-Type:``
196 Must be ``text/plain``. Mandatory. 227 Must be ``text/plain``. Mandatory.
197 228
198``Posted:`` 229``Posted:``
199 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
200 compatibility with GLEP 1 [#glep-1]_. UTC time in ``hh-mm-ss +0000`` format 231 compatibility with GLEP 45 [#glep-45]_. Mandatory.
201 may also be included. Mandatory.
202 232
203``Revision:`` 233``Revision:``
204 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
205 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
206 file. Mandatory. 237 item. Mandatory.
207 238
208``News-Item-Format:`` 239``News-Item-Format:``
209 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
210 number for backwards-compatible changes, or the major number for major 241 number for backwards-compatible changes, or the major number for major
211 changes. 242 changes.
212 243
213The following headers are used for filtering: 244The following headers are used for filtering:
214 245
215``Display-If-Installed:`` 246``Display-If-Installed:``
216 A dependency atom or simple package name (for example, 247 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 248 ``net-www/apache``). If the user has the package specified installed from
218 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.
219 251
220``Display-If-Keyword:`` 252``Display-If-Keyword:``
221 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
222 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.
223 255
224``Display-If-Profile:`` 256``Display-If-Profile:``
225 A profile path, for example ``default-linux/sparc/sparc64/server``. Standard 257 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 258 user is using the exact profile in question, or a subprofile of this
227 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
228 replace ``deprecated`` files in the future. 260 replace ``deprecated`` files in the future.
229 261
230.. Note:: When performing package moves, developers must also update any 262.. Note:: When performing package moves, developers must also update any
231 relevant ``Display-If-Installed`` headers in news files. 263 relevant ``Display-If-Installed`` headers in news files.
232 264
262 294
263Hyperlinks 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
264guide). 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
265simply 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
266a 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
267administrated — 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.
268 300
269Example News Item 301Example News Item
270''''''''''''''''' 302'''''''''''''''''
271 303
272`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
287posted 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``
288(exceptions may be made in exceptional circumstances). Any complaints — for 320(exceptions may be made in exceptional circumstances). Any complaints — for
289example regarding wording, clarity or accuracy — **must** be addressed before 321example regarding wording, clarity or accuracy — **must** be addressed before
290the news item goes live. 322the news item goes live.
291 323
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 324News items must only be for **important** changes that may cause serious upgrade
299or compatibility problems. Ordinary upgrade messages and non-critical news items 325or compatibility problems. Ordinary upgrade messages and non-critical news items
300should remain in ``einfo`` notices. The importance of the message to its 326should remain in ``einfo`` notices. The importance of the message to its
301intended audience should be justified with the proposal. 327intended audience should be justified with the proposal.
302 328
326the 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
32712 for December). This separation will help keep news items more manageable. 35312 for December). This separation will help keep news items more manageable.
328 354
329The 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
330tree, 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
331merging 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
332already used for merging GLSAs into the rsync tree. 358of this GLEP; a similar setup is already used for merging GLSAs into the rsync
359tree.
333 360
334The 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.
335 364
336Client Side 365Client Side
337''''''''''' 366'''''''''''
338 367
339Whenever 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
340file named ``/var/lib/gentoo/news/news-magic-chicken.unread`` (if it does not 369file named ``/var/lib/gentoo/news/news-${repoid}.unread`` (if it does not
341already exist) and append the news item identifier (eg 370already exist) and append the news item identifier (eg
342``2005-11-01-yoursql-updates``) on a new line. 371``2005-11-01-yoursql-updates``) on a new line.
343 372
344.. Note:: Future changes to Portage involving support for multiple repositories 373All 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 374with the group write (and, for directories, execute) bits set. News files should
346 filename should be replaced by a string representation of the repository 375be world readable.
347 name. Thus, news item clients should use a wildcard rather than hardcoding
348 the ``magic-chicken`` string.
349 376
350Notification that new relevant news items will be displayed via the 377Notification that new relevant news items will be displayed via the
351``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
352updating" messages: 379updating" messages:
353 380
359Checks for new news messages should be displayed: 386Checks for new news messages should be displayed:
360 387
361* After an ``emerge sync`` 388* After an ``emerge sync``
362* After an ``emerge --pretend`` 389* After an ``emerge --pretend``
363* 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)
364* 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.
365 395
366The 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
367news items unnecessarily. 397news items unnecessarily.
368 398
369The 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
370to 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
371be handled via a ``news-magic-chicken.skip`` file, but implementation is not 401be handled via a ``news-${repoid}.skip`` file containing the IDs of news items
372specified by this GLEP. 402that have already been added to a ``news-${repoid}.unread`` file, but this
403method is not required by this GLEP.
373 404
374Users 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
375filter out the ``metadata/news/`` directory. 406filter out the ``metadata/news/`` directory.
376 407
377News Item Clients 408News Item Clients
379 410
380Once 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
381Unix tools) can be used to display and view the news files. 412Unix tools) can be used to display and view the news files.
382 413
383When a news item is read, its name should be removed from the 414When 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 415``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 416rather 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 417file in the same directory with the same file format.
387format (again, ``magic-chicken`` should be a wildcard rather than hardcoded).
388 418
389An ``eselect`` [#eselect]_ module shall be created as the 'suggested' display 419An ``eselect`` [#eselect]_ module shall be created as the 'suggested' display
390tool; 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
391be 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
392desire them. 422desire them.
437 467
438The 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
439Herbert [#stuart-blog]_. 469Herbert [#stuart-blog]_.
440 470
441Thanks to Lance Albertson, Stephen Bennett, Donnie Berkholz, Grant Goodyear, 471Thanks to Lance Albertson, Stephen Bennett, Donnie Berkholz, Grant Goodyear,
442Brian 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
443input. Some of the ideas presented here are theirs, others go completely 473Warner for input. Some of the ideas presented here are theirs, others go
444against their suggestions. 474completely against their suggestions.
445 475
446Example Files 476Example Files
447============= 477=============
448 478
449TODO Removed until the exact format details are figured out. 479TODO Removed until the exact format details are figured out.
461 http://www.gentoo.org/proj/en/eselect/index.xml 491 http://www.gentoo.org/proj/en/eselect/index.xml
462.. [#forums-glsa] Forums user GLSA, 492.. [#forums-glsa] Forums user GLSA,
463 http://forums.gentoo.org/profile.php?mode=viewprofile&u=55648 493 http://forums.gentoo.org/profile.php?mode=viewprofile&u=55648
464.. [#forums-apache2] Forums thread "Gentoo Apache2 Config Change Idiocy", 494.. [#forums-apache2] Forums thread "Gentoo Apache2 Config Change Idiocy",
465 http://forums.gentoo.org/viewtopic-t-384368.html 495 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 496.. [#glep-22] GLEP 22: "New "keyword" system to incorporate various
469 userlands/kernels/archs", Grant Goodyear, 497 userlands/kernels/archs", Grant Goodyear,
470 http://www.gentoo.org/proj/en/glep/glep-0022.html 498 http://www.gentoo.org/proj/en/glep/glep-0022.html
471.. [#glep-31] GLEP 31: "Character Sets for Portage Tree Items", Ciaran 499.. [#glep-31] GLEP 31: "Character Sets for Portage Tree Items", Ciaran
472 McCreesh, 500 McCreesh,
474.. [#glep-34] GLEP 34: "Per-Category metadata.xml Files", Ciaran McCreesh, 502.. [#glep-34] GLEP 34: "Per-Category metadata.xml Files", Ciaran McCreesh,
475 http://www.gentoo.org/proj/en/glep/glep-0034.html 503 http://www.gentoo.org/proj/en/glep/glep-0034.html
476.. [#glep-36] GLEP 36: "Subversion/CVS for Gentoo Hosted Projects", Aaron 504.. [#glep-36] GLEP 36: "Subversion/CVS for Gentoo Hosted Projects", Aaron
477 Walker, 505 Walker,
478 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
479.. [#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"
480.. [#ramereth-repo] "Re: [gentoo-dev] GLEP ??: Critical News Reporting", Lance 510.. [#ramereth-repo] "Re: [gentoo-dev] GLEP ??: Critical News Reporting", Lance
481 Albertson, 511 Albertson,
482 http://marc.theaimsgroup.com/?l=gentoo-dev&m=113111585907703&w=2 512 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" 513.. [#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.7

  ViewVC Help
Powered by ViewVC 1.1.20