/[gentoo]/xml/htdocs/proj/en/glep/glep-0042.txt
Gentoo

Contents of /xml/htdocs/proj/en/glep/glep-0042.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.5 - (hide annotations) (download)
Tue Dec 13 03:21:59 2005 UTC (8 years, 6 months ago) by ciaranm
Branch: MAIN
Changes since 1.4: +19 -13 lines
File MIME type: text/plain
New glep 42 draft

1 g2boojum 1.1 GLEP: 42
2     Title: Critical News Reporting
3 ciaranm 1.4 Version: $Revision: $
4 g2boojum 1.1 Author: Ciaran McCreesh <ciaranm@gentoo.org>
5 ciaranm 1.4 Last-Modified: $Date: $
6 g2boojum 1.1 Status: Draft
7     Type: Standards Track
8     Content-Type: text/x-rst
9 ciaranm 1.3 Created: 31-Oct-2005
10 ciaranm 1.5 Post-History: 1-Nov-2005, 5-Nov-2005, 7-Nov-2005, 11-Dec-2005, 13-Dec-2005
11 g2boojum 1.1
12     Abstract
13     ========
14    
15     This GLEP proposes a new way of informing users about important updates and news
16     regarding tree-related items.
17    
18     Motivation
19     ==========
20    
21 ciaranm 1.4 Although most package updates are clean and require little user action,
22     occasionally an upgrade requires user intervention during the upgrade process.
23     Recent examples of the latter include the ``gcc-3.4`` stabilisation on ``x86``
24 ciaranm 1.5 and the ``mysql-4.1`` database format changes.
25 ciaranm 1.4
26     There are currently several ways of delivering important news items to our
27     users, none of them particularly effective:
28 g2boojum 1.1
29     * Gentoo Weekly News
30 ciaranm 1.4 * The ``gentoo-announce``, ``gentoo-user`` and ``gentoo-dev`` mailing lists
31 g2boojum 1.1 * The Gentoo Forums
32     * The main Gentoo website
33     * RSS feeds of Gentoo news
34 ciaranm 1.5 * ``einfo`` and ``ewarn`` messages in ``pkg_setup`` or ``pkg_postinst``
35 g2boojum 1.1
36     A more reliable way of getting news of critical updates out to users is required
37     to avoid repeats of the various recent upgrade debacles. This GLEP proposes a
38     solution based around pushing news items out to the user via the ``rsync`` tree.
39    
40 ciaranm 1.4 .. 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
42     by ``elog`` [#bug-11359]_.
43    
44 g2boojum 1.1 Requirements
45     ============
46    
47     An adequate solution must meet all of the following requirements:
48    
49     Preemptive
50 ciaranm 1.4 Users should be told of changes *before* they break a system, not after the
51     damage has already been done. Ideally, the system administrator would be
52     given ample warning to plan difficult upgrades and changes, rather than only
53     being told just before action is necessary.
54 g2boojum 1.1
55     No user subscription required
56 ciaranm 1.4 It has already been demonstrated [#forums-apache2]_ that many users do not
57 g2boojum 1.1 read the ``gentoo-announce`` mailing list or ``RSS`` feeds. A solution which
58     requires subscription has no advantage over current methods.
59    
60     No user monitoring required
61 ciaranm 1.4 It has already been demonstrated [#forums-apache2]_ that many users do not
62 g2boojum 1.1 read news items posted to the Gentoo website, or do not read news items
63     until it is too late. A solution that relies upon active monitoring of a
64     particular source has no advantage over current methods.
65    
66     Relevant
67     System administrators who do not use a particular package should not have to
68     read news items which affect purely that package. Some news items may be of
69     relevance to most or all users, but those that are not should not be forced
70     upon users unnecessarily.
71    
72     Lightweight
73     It is not reasonable to expect all users to have an MTA, web browser, email
74     client, cron daemon or text processing suite available on their system.
75 ciaranm 1.4 Users must not be forced to install unreasonable extra software to be able
76     to read news items.
77 g2boojum 1.1
78     No privacy violations
79     Users of the solution should not be required to provide information about
80     their systems (for example, IP addresses or installed packages).
81    
82     Multiple delivery method support
83     Some users may wish to view news items via email, some via a terminal and
84     some via a web browser. A solution should either support all of these
85 ciaranm 1.4 methods or (better still) make it simple to write clients for displaying
86 g2boojum 1.1 news items in different ways.
87    
88     The following characteristics would be desirable:
89    
90     Internationalisable
91     Being able to provide messages in multiple languages may be beneficial.
92    
93     Quality control
94     There should be some way to ensure that badly written or irrelevant messages
95 ciaranm 1.4 are not sent out, for example by inexperienced developers or those whose
96     English language skills are below par.
97 g2boojum 1.1
98     Simple for developers
99     Posting news items should be as simple as is reasonably possible.
100    
101     Simple for users
102     Reading relevant news items should be as simple as is reasonably possible.
103    
104     Compatibility with existing and future news sources
105     A news system would ideally be able to be integrated with existing news
106     sources (for example, Forums, GWN, the main Gentoo website) without
107     excessive difficulty. Similarly, easy interoperation with any future news
108     sources should not be precluded.
109    
110     Specification
111     =============
112    
113     Overview
114     --------
115    
116     News items are published and delivered to users as follows:
117    
118 ciaranm 1.4 1. A news item is written. The format to be used is described below.
119    
120 g2boojum 1.1 2. The news item is reviewed, following the process described in
121     `News Item Quality Control`_.
122 ciaranm 1.4
123 g2boojum 1.1 3. The news item is committed to a CVS (or Subversion [#glep-36]_) repository.
124     From here, it is merged with the rsync tree. This is described in `News Item
125     Distribution`_.
126 ciaranm 1.4
127     4. Users fetch the news item when they sync. This ensures that the news items in
128 g2boojum 1.1 question are pushed to the user before the user accidentally makes an
129     unwanted change. No changes to the existing rsync process are required by
130     this GLEP.
131 ciaranm 1.4
132     5. The package manager filters the news item and, if it is relevant, marks the
133     news item for reading. The package manager should also display a notice
134     informing the user that there are unread news items.
135    
136     6. The news item is handled by the user's choice of news item reader. See `News
137 g2boojum 1.1 Item Clients`_.
138    
139 ciaranm 1.4 News Item Identities
140     --------------------
141    
142     Each news item will have a unique identifier. This identifier will be in the
143     form ``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
145     (``01`` through ``31``). The ``short-name`` is a very short name describing the
146     news item (e.g. ``yoursql-updates``), consisting only of the characters ``a-z``,
147 ciaranm 1.5 ``0-9``, ``+`` (plus), ``:`` (colon) and ``-`` (hyphen).
148 ciaranm 1.4
149     News Item Directories
150 g2boojum 1.1 ---------------------
151    
152 ciaranm 1.4 Each news item will be represented by a directory whose name is the same as the
153     news item's identifier.
154    
155     The directory will contain a file named ``yyyy-mm-dd-short-name.en.txt``, which
156     contains the text of the news item, in English, in the format described below.
157    
158     If a news item is translated, other files named ``yyyy-mm-dd-short-name.xx.txt``
159     (where ``xx`` is the ISO 639 [#iso-639]_ two letter country code) will also be
160     provided. However, only the English version of a news item is authoritative.
161     This anglocentricity is justified by precedent [#glep-34]_.
162    
163     News Item Files
164     ---------------
165    
166     A news item file is a text file, encoded using UTF-8 [#rfc-3629]_ for
167     compatibility with and for the same reasons as existing Gentoo documentation
168     [#docs-policy]_ and the tree [#glep-31]_.
169 g2boojum 1.1
170 ciaranm 1.4 News items should be signed with a detached GPG signature: ::
171    
172     gpg --armour --detach-sign ????-??-??-*.??.txt
173    
174     A news item file's content will consist of an RFC 822 style header [#rfc-822]_
175 g2boojum 1.1 followed by the main body of the message as plain text. This GLEP defines
176 ciaranm 1.4 various optional and mandatory headers. Future GLEPs may propose new headers —
177 g2boojum 1.1 tools handling these news items must ignore any unrecognised header.
178    
179     News Item Headers
180     '''''''''''''''''
181    
182     The following headers describe the purpose and format of the news item:
183    
184     ``Title:``
185     A short (maximum 44 characters) descriptive title. Mandatory.
186 ciaranm 1.4
187 g2boojum 1.1 ``Author:``
188     Author's name and email address, in the form ``Real Name <email@address>``.
189 ciaranm 1.4 Mandatory; multiple author headers may be specified if appropriate.
190    
191 g2boojum 1.1 ``Translator:``
192 ciaranm 1.4 For translated news items, the translator's name and email address. Multiple
193     translator headers may be specified if appropriate.
194    
195 g2boojum 1.1 ``Content-Type:``
196     Must be ``text/plain``. Mandatory.
197 ciaranm 1.4
198 g2boojum 1.1 ``Posted:``
199 ciaranm 1.4 Date of posting, in ``dd-mmm-yyyy`` format (e.g. 14-Aug-2001) for
200     compatibility with GLEP 1 [#glep-1]_. UTC time in ``hh-mm-ss +0000`` format
201     may also be included. Mandatory.
202    
203     ``Revision:``
204 g2boojum 1.1 Initially 1. Incremented every time a non-trivial change is made. Changes
205     which require a re-read of the news item should instead use a new news item
206 ciaranm 1.4 file. Mandatory.
207    
208 g2boojum 1.1 ``News-Item-Format:``
209     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
211     changes.
212    
213 ciaranm 1.4 The following headers are used for filtering:
214 g2boojum 1.1
215     ``Display-If-Installed:``
216     A dependency atom or simple package name (for example,
217     ``<dev-lang/php-5_alpha`` or ``net-www/apache``). If the user has the
218     package specified installed, the news item should be displayed.
219    
220     ``Display-If-Keyword:``
221 ciaranm 1.4 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.
223 g2boojum 1.1
224     ``Display-If-Profile:``
225 ciaranm 1.4 A profile path, for example ``default-linux/sparc/sparc64/server``. Standard
226     shell GLOB wildcards may be used. If the user is using the exact profile in
227     question, the news item should be displayed. This header may be used to
228     replace ``deprecated`` files in the future.
229    
230     .. Note:: When performing package moves, developers must also update any
231     relevant ``Display-If-Installed`` headers in news files.
232    
233     The algorithm used to determine whether a news item is 'relevant' is as
234     follows:
235    
236     * For each ``Display-If-`` header type which occurs at least once:
237    
238     + The news item is not relevant if none of the headers of this type are
239     successfully matched.
240    
241     * Otherwise the news item is relevant.
242    
243     In particular, if no ``Display-If-`` header is specified, a news item will be
244     relevant for all users.
245    
246     This algorithm was chosen because it makes conditions like "display this news
247     item for ``YourSQL`` users who are on ``sparc`` or ``x86-obsd`` relatively
248     simple to specify — it is believed that these kinds of condition are far more
249     likely to occur than "display this news item for people using ``YourSQL``, or
250     for people on ``sparc`` or ``x86-obsd``\" or "display these news items for
251     people who use ``YourSQL`` and who are on both ``sparc`` and ``x86-obsd``\".
252 g2boojum 1.1
253     News Item Body
254     ''''''''''''''
255    
256     The header section must be followed by a blank line, then the main body of the
257     text.
258    
259     The text body should be wrapped at 72 characters. No fancy formatting or tab
260 ciaranm 1.4 characters should be used — the news item may be being displayed directly to a
261 ciaranm 1.2 terminal. Paragraphs should be separated by a blank line.
262 g2boojum 1.1
263     Hyperlinks may be used to refer to further information (for example, an upgrade
264     guide). However, the main body of the news item should be descriptive and not
265     simply a "read this link" text. It is assumed that the user will have access to
266     a web browser *somewhere*, but not necessarily on the box which is being
267 ciaranm 1.4 administrated — this will be the case on may servers and routers, for example.
268 g2boojum 1.1
269     Example News Item
270     '''''''''''''''''
271    
272 ciaranm 1.4 `This hypothetical news item`__ could be used for an upgrade to the
273     ``YourSQL`` database format which breaks forward compatibility.
274 g2boojum 1.1
275 ciaranm 1.4 .. __: glep-0042-extras/example-news-item.txt
276 g2boojum 1.1
277     News Item Quality Control
278     -------------------------
279    
280     There have been complaints regarding the comprehensibility of some upgrade
281 ciaranm 1.4 notices and news items in the past. This is understandable — not every Gentoo
282     developer speaks English as a first language. However, for the sake of clarity,
283     professionalism and avoiding making us look like prats, it is important that any
284     language problems be corrected before inflicting a news item upon end users.
285    
286     Thus, at least 72 hours before a proposed news item is committed, it must be
287     posted to the ``gentoo-dev`` mailing list and ``Cc:``\ed to ``pr@gentoo.org``
288     (exceptions may be made in exceptional circumstances). Any complaints — for
289     example regarding wording, clarity or accuracy — **must** be addressed before
290     the news item goes live.
291    
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 g2boojum 1.1
298     News items must only be for **important** changes that may cause serious upgrade
299     or compatibility problems. Ordinary upgrade messages and non-critical news items
300     should remain in ``einfo`` notices. The importance of the message to its
301     intended audience should be justified with the proposal.
302    
303     .. Important:: The filtering system means that it is appropriate to send out
304     news items which are aimed at users of an uncommon package or architecture.
305     Thus, the justification should be in the form "this message is important to
306     YourSQL users because ...", not "YourSQL is important because ...".
307    
308     News Item Distribution
309     ----------------------
310    
311     Server Side
312     '''''''''''
313    
314 ciaranm 1.4 News items are to be made available via the standard rsync tree. This removes
315     any need for polling of a remote source.
316 g2boojum 1.1
317     A new repository will be created for news items. The type (CVS or Subversion),
318     location and access controls on this repository are beyond the scope of this
319     GLEP.
320    
321     .. Note:: A previous draft of this GLEP instead used the main ``gentoo-x86``
322     tree. This was changed following advice from Infrastructure
323     [#ramereth-repo]_. Both solutions have the same end result.
324    
325 ciaranm 1.4 This repository will contain directories named ``yyyy/mm/``, where ``yyyy`` is
326 g2boojum 1.1 the current year and ``mm`` is the current month number (01 for January through
327     12 for December). This separation will help keep news items more manageable.
328    
329     The contents of this repository will automatically be merged with the main rsync
330 ciaranm 1.4 tree, placing the items in a ``metadata/news/`` directory. The method used for
331     merging these items is beyond the scope of this GLEP — a similar setup is
332 g2boojum 1.1 already used for merging GLSAs into the rsync tree.
333    
334 ciaranm 1.4 The main rsync tree will **not** use the ``yyyy/mm/`` subdirectory layout.
335 g2boojum 1.1
336     Client Side
337     '''''''''''
338    
339 ciaranm 1.4 Whenever relevant unread news items are found, the package manager will create a
340 ciaranm 1.5 file named ``/var/lib/gentoo/news/news-magic-chicken.unread`` (if it does not
341     already exist) and append the news item identifier (eg
342     ``2005-11-01-yoursql-updates``) on a new line.
343 ciaranm 1.4
344     .. Note:: Future changes to Portage involving support for multiple repositories
345 ciaranm 1.5 may introduce repository names. In this case, the ``magic-chicken`` part of the
346     filename should be replaced by a string representation of the repository
347     name. Thus, news item clients should use a wildcard rather than hardcoding
348     the ``magic-chicken`` string.
349 g2boojum 1.1
350     Notification that new relevant news items will be displayed via the
351     ``emerge`` tool in a similar way to the existing "configuration files need
352     updating" messages:
353    
354     ::
355    
356     * Important: there are 5 unread news items.
357     * Type emerge --help news to learn how to read news files.
358    
359 ciaranm 1.4 Checks for new news messages should be displayed:
360 g2boojum 1.1
361 ciaranm 1.4 * After an ``emerge sync``
362     * After an ``emerge --pretend``
363     * Before an ``emerge <target>`` (which may also include a red warning message)
364 ciaranm 1.5 * Before an ``emerge --ask <target>`` sequence
365 ciaranm 1.4
366     The package manager may use a timestamp check file to avoid having to process
367     news items unnecessarily.
368    
369     The package manager must keep track of news items that have already been added
370     to the unread list to avoid repeatedly marking a deleted news item. This could
371 ciaranm 1.5 be handled via a ``news-magic-chicken.skip`` file, but implementation is not
372     specified by this GLEP.
373 g2boojum 1.1
374     Users who really don't care about news items can use ``rsync_excludes`` to
375 ciaranm 1.4 filter out the ``metadata/news/`` directory.
376 g2boojum 1.1
377     News Item Clients
378     -----------------
379    
380 ciaranm 1.4 Once a news item is marked for reading, third party tools (or traditional core
381     Unix tools) can be used to display and view the news files.
382    
383 ciaranm 1.5 When 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
385     reader rather than a gateway, it should then add the name to a
386     ``news-magic-chicken.read`` file in the same directory with the same file
387     format (again, ``magic-chicken`` should be a wildcard rather than hardcoded).
388 ciaranm 1.4
389     An ``eselect`` [#eselect]_ module shall be created as the 'suggested' display
390     tool; other display tools (for example, a news to email forwarder, which would
391     be ideal for users who sync on a ``cron``) are left as options for those who
392     desire them.
393 g2boojum 1.1
394     News Item Removal
395     -----------------
396    
397     News items can be removed (by removing the news file from the main tree) when
398     they are no longer relevant, if they are made obsolete by a future news item or
399     after a long period of time. This is the same as the method used for ``updates``
400     entries.
401    
402     Integration with Existing Systems
403     =================================
404    
405 ciaranm 1.4 It would be simple to convert these news items into the format used for news
406 g2boojum 1.1 items on the Gentoo website or posts for the ``gentoo-announce`` mailing list.
407    
408     There is an existing automated tool [#forums-glsa]_ for posting GLSAs to the
409     forums. A similar tool can be used for these news items.
410    
411     Backwards Compatibility
412     =======================
413    
414     Backwards compatibility is not a concern here. Existing tools will simply ignore
415     the ``news/`` directory.
416    
417     Reference Implementation
418     ========================
419    
420     Portage Code
421     ------------
422    
423     TODO
424    
425     Simple ``eselect`` News Client
426     ------------------------------
427    
428 ciaranm 1.4 TODO Removed until the exact format details are figured out.
429 g2boojum 1.1
430     Simple News to Mail Forwarder
431     -----------------------------
432    
433 ciaranm 1.4 TODO Removed until the exact format details are figured out.
434 g2boojum 1.1
435     Credits
436     =======
437    
438     The idea behind notifying users of news updates via Portage comes from Stuart
439     Herbert [#stuart-blog]_.
440    
441 ciaranm 1.4 Thanks to Lance Albertson, Stephen Bennett, Donnie Berkholz, Grant Goodyear,
442     Brian Harring, Dan Meltzer, Jason Stubbs, Paul de Vrieze and Alec Warner for
443     input. Some of the ideas presented here are theirs, others go completely
444     against their suggestions.
445    
446     Example Files
447     =============
448    
449     TODO Removed until the exact format details are figured out.
450 g2boojum 1.1
451     References
452     ==========
453    
454 ciaranm 1.4 .. [#bug-11359] Bugzilla Bug 11359
455     "[NEW FEATURE] pkg_postinst/pkg_preinst ewarn/einfo logging",
456     https://bugs.gentoo.org/show_bug.cgi?id=11359
457 g2boojum 1.1 .. [#docs-policy] Gentoo XML Guide, Daniel Robbins et al.,
458     http://www.gentoo.org/doc/en/xml-guide.xml
459     .. [#eselect] eselect modular framework for configuration and
460     administration utilities,
461     http://www.gentoo.org/proj/en/eselect/index.xml
462     .. [#forums-glsa] Forums user GLSA,
463     http://forums.gentoo.org/profile.php?mode=viewprofile&u=55648
464 ciaranm 1.4 .. [#forums-apache2] Forums thread "Gentoo Apache2 Config Change Idiocy",
465 g2boojum 1.1 http://forums.gentoo.org/viewtopic-t-384368.html
466 ciaranm 1.4 .. [#glep-1] GLEP 1: "GLEP Purpose and Guidelines", Grant Goodyear,
467     http://www.gentoo.org/proj/en/glep/glep-0001.html
468 g2boojum 1.1 .. [#glep-22] GLEP 22: "New "keyword" system to incorporate various
469     userlands/kernels/archs", Grant Goodyear,
470     http://www.gentoo.org/proj/en/glep/glep-0022.html
471     .. [#glep-31] GLEP 31: "Character Sets for Portage Tree Items", Ciaran
472     McCreesh,
473     http://www.gentoo.org/proj/en/glep/glep-0031.html
474     .. [#glep-34] GLEP 34: "Per-Category metadata.xml Files", Ciaran McCreesh,
475     http://www.gentoo.org/proj/en/glep/glep-0034.html
476     .. [#glep-36] GLEP 36: "Subversion/CVS for Gentoo Hosted Projects", Aaron
477     Walker,
478     http://www.gentoo.org/proj/en/glep/glep-0036.html
479     .. [#iso-639] ISO 639 "Code for the representation of names of languages"
480     .. [#ramereth-repo] "Re: [gentoo-dev] GLEP ??: Critical News Reporting", Lance
481     Albertson,
482     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"
484 ciaranm 1.4 .. [#rfc-3629] RFC 3629: "UTF-8, a transformation format of ISO 10646"
485     http://www.ietf.org/rfc/rfc3629.txt
486 g2boojum 1.1 .. [#stuart-blog] "Favouring an automatic news mechanism", Stuart Herbert,
487     http://stu.gnqs.org/diary/gentoo.php/2005/10/28/favouring_an_automatic_news_mechanism
488    
489     Copyright
490     =========
491    
492     This document has been placed in the public domain.
493    
494     .. vim: set tw=80 fileencoding=utf-8 spell spelllang=en et :

  ViewVC Help
Powered by ViewVC 1.1.20