1 | GLEP: 42 |
1 | GLEP: 42 |
2 | Title: Critical News Reporting |
2 | Title: Critical News Reporting |
3 | Version: $Revision: 1.1 $ |
3 | Version: $Revision: 1.6 $ |
4 | Author: Ciaran McCreesh <ciaranm@gentoo.org> |
4 | Author: Ciaran McCreesh <ciaranm@gentoo.org> |
5 | Last-Modified: $Date: 2005/11/05 03:32:09 $ |
5 | Last-Modified: $Date: 2005/12/18 04:16:44 $ |
6 | Status: Draft |
6 | Status: Draft |
7 | Type: Standards Track |
7 | Type: Standards Track |
8 | Content-Type: text/x-rst |
8 | Content-Type: text/x-rst |
9 | Created: 31-October-2005 |
9 | Created: 31-Oct-2005 |
10 | Post-Date: 1-November-2005, 5-November-2005 |
10 | Post-History: 1-Nov-2005, 5-Nov-2005, 7-Nov-2005, 11-Dec-2005, 13-Dec-2005, 18-Dec-2005 |
11 | |
11 | |
12 | Abstract |
12 | Abstract |
13 | ======== |
13 | ======== |
14 | |
14 | |
15 | This GLEP proposes a new way of informing users about important updates and news |
15 | This GLEP proposes a new way of informing users about important updates and news |
16 | regarding tree-related items. |
16 | regarding tree-related items. |
17 | |
17 | |
18 | Motivation |
18 | Motivation |
19 | ========== |
19 | ========== |
20 | |
20 | |
21 | There are currently several ways of getting news out to our users, none of them |
21 | Although most package updates are clean and require little user action, |
22 | particularly effective: |
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 | and the ``mysql-4.1`` database format changes. |
|
|
25 | |
|
|
26 | There are currently several ways of delivering important news items to our |
|
|
27 | users, none of them particularly effective: |
23 | |
28 | |
24 | * Gentoo Weekly News |
29 | * Gentoo Weekly News |
25 | * The ``gentoo-announce`` mailing list |
30 | * The ``gentoo-announce``, ``gentoo-user`` and ``gentoo-dev`` mailing lists |
26 | * The Gentoo Forums |
31 | * The Gentoo Forums |
27 | * The main Gentoo website |
32 | * The main Gentoo website |
28 | * RSS feeds of Gentoo news |
33 | * RSS feeds of Gentoo news |
|
|
34 | * ``einfo`` and ``ewarn`` messages in ``pkg_setup`` or ``pkg_postinst`` |
29 | |
35 | |
30 | A more reliable way of getting news of critical updates out to users is required |
36 | A more reliable way of getting news of critical updates out to users is required |
31 | to avoid repeats of the various recent upgrade debacles. This GLEP proposes a |
37 | to avoid repeats of the various recent upgrade debacles. This GLEP proposes a |
32 | solution based around pushing news items out to the user via the ``rsync`` tree. |
38 | solution based around pushing news items out to the user via the ``rsync`` tree. |
33 | |
39 | |
|
|
40 | .. 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 | |
34 | Requirements |
44 | Requirements |
35 | ============ |
45 | ============ |
36 | |
46 | |
37 | An adequate solution must meet all of the following requirements: |
47 | An adequate solution must meet all of the following requirements: |
38 | |
48 | |
39 | Preemptive |
49 | Preemptive |
40 | Users should be told of changes *before* they break the user's system, |
50 | Users should be told of changes *before* they break a system, not after the |
41 | after the damage has already been done. |
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. |
42 | |
54 | |
43 | No user subscription required |
55 | No user subscription required |
44 | It has already been demonstrated [#forums-whining]_ that many users do not |
56 | It has already been demonstrated [#forums-apache2]_ that many users do not |
45 | read the ``gentoo-announce`` mailing list or ``RSS`` feeds. A solution which |
57 | read the ``gentoo-announce`` mailing list or ``RSS`` feeds. A solution which |
46 | requires subscription has no advantage over current methods. |
58 | requires subscription has no advantage over current methods. |
47 | |
59 | |
48 | No user monitoring required |
60 | No user monitoring required |
49 | It has already been demonstrated [#forums-whining]_ that many users do not |
61 | It has already been demonstrated [#forums-apache2]_ that many users do not |
50 | read news items posted to the Gentoo website, or do not read news items |
62 | read news items posted to the Gentoo website, or do not read news items |
51 | until it is too late. A solution that relies upon active monitoring of a |
63 | until it is too late. A solution that relies upon active monitoring of a |
52 | particular source has no advantage over current methods. |
64 | particular source has no advantage over current methods. |
53 | |
65 | |
54 | Relevant |
66 | Relevant |
… | |
… | |
58 | upon users unnecessarily. |
70 | upon users unnecessarily. |
59 | |
71 | |
60 | Lightweight |
72 | Lightweight |
61 | It is not reasonable to expect all users to have an MTA, web browser, email |
73 | It is not reasonable to expect all users to have an MTA, web browser, email |
62 | client, cron daemon or text processing suite available on their system. |
74 | client, cron daemon or text processing suite available on their system. |
|
|
75 | Users must not be forced to install unreasonable extra software to be able |
|
|
76 | to read news items. |
63 | |
77 | |
64 | No privacy violations |
78 | No privacy violations |
65 | Users of the solution should not be required to provide information about |
79 | Users of the solution should not be required to provide information about |
66 | their systems (for example, IP addresses or installed packages). |
80 | their systems (for example, IP addresses or installed packages). |
67 | |
81 | |
68 | Multiple delivery method support |
82 | Multiple delivery method support |
69 | Some users may wish to view news items via email, some via a terminal and |
83 | Some users may wish to view news items via email, some via a terminal and |
70 | some via a web browser. A solution should either support all of these |
84 | some via a web browser. A solution should either support all of these |
71 | methods or (better still) make it trivial to write clients for displaying |
85 | methods or (better still) make it simple to write clients for displaying |
72 | news items in different ways. |
86 | news items in different ways. |
73 | |
87 | |
74 | The following characteristics would be desirable: |
88 | The following characteristics would be desirable: |
75 | |
89 | |
76 | Internationalisable |
90 | Internationalisable |
77 | Being able to provide messages in multiple languages may be beneficial. |
91 | Being able to provide messages in multiple languages may be beneficial. |
78 | |
92 | |
79 | Quality control |
93 | Quality control |
80 | There should be some way to ensure that badly written or irrelevant messages |
94 | There should be some way to ensure that badly written or irrelevant messages |
81 | are not sent out, for example by inexperienced developers, those whose |
95 | are not sent out, for example by inexperienced developers or those whose |
82 | English language skills are below par or morons. |
96 | English language skills are below par. |
83 | |
97 | |
84 | Simple for developers |
98 | Simple for developers |
85 | Posting news items should be as simple as is reasonably possible. |
99 | Posting news items should be as simple as is reasonably possible. |
86 | |
100 | |
87 | Simple for users |
101 | Simple for users |
… | |
… | |
99 | Overview |
113 | Overview |
100 | -------- |
114 | -------- |
101 | |
115 | |
102 | News items are published and delivered to users as follows: |
116 | News items are published and delivered to users as follows: |
103 | |
117 | |
104 | 1. A news item is written. The format to be used is described in |
118 | 1. A news item is written. The format to be used is described below. |
105 | `News Item File Format`_. |
119 | |
106 | 2. The news item is reviewed, following the process described in |
120 | 2. The news item is reviewed, following the process described in |
107 | `News Item Quality Control`_. |
121 | `News Item Quality Control`_. |
|
|
122 | |
108 | 3. The news item is committed to a CVS (or Subversion [#glep-36]_) repository. |
123 | 3. The news item is committed to a CVS (or Subversion [#glep-36]_) repository. |
109 | From here, it is merged with the rsync tree. This is described in `News Item |
124 | From here, it is merged with the rsync tree. This is described in `News Item |
110 | Distribution`_. |
125 | Distribution`_. |
111 | 4. The news item is merged with the rsync tree. Implementation details of this |
126 | |
112 | point are beyond the scope of this GLEP; existing solutions are in place |
|
|
113 | for merging GLSAs to the tree. |
|
|
114 | 5. Users fetch the news item when they sync. This ensures that the news items in |
127 | 4. Users fetch the news item when they sync. This ensures that the news items in |
115 | question are pushed to the user before the user accidentally makes an |
128 | question are pushed to the user before the user accidentally makes an |
116 | unwanted change. No changes to the existing rsync process are required by |
129 | unwanted change. No changes to the existing rsync process are required by |
117 | this GLEP. |
130 | this GLEP. |
118 | 6. Portage filters the news item and, if it is relevant, installs it in a |
131 | |
119 | special location to be read by a news item reader. Messages are also |
132 | 5. The package manager filters the news item and, if it is relevant, marks the |
120 | displayed to inform the user that news is available. |
133 | news item for reading. The package manager should also display a notice |
|
|
134 | informing the user that there are unread news items. |
|
|
135 | |
121 | 7. The news item is handled by the user's choice of news item reader. See `News |
136 | 6. The news item is handled by the user's choice of news item reader. See `News |
122 | Item Clients`_. |
137 | Item Clients`_. |
123 | |
138 | |
124 | News Item File Format |
139 | Required Portage Enhancements |
|
|
140 | ----------------------------- |
|
|
141 | |
|
|
142 | The following extensions to Portage are required: |
|
|
143 | |
|
|
144 | TODO: ferringb wants spaces added to the first item on the list. I don't, |
|
|
145 | because 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 | |
|
|
167 | These extensions are assumed during the following specification. |
|
|
168 | |
|
|
169 | News Item Identities |
|
|
170 | -------------------- |
|
|
171 | |
|
|
172 | Each news item will have a unique identifier. This identifier will be in the |
|
|
173 | form ``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 |
|
|
175 | (``01`` through ``31``). The ``short-name`` is a very short name describing the |
|
|
176 | news item (e.g. ``yoursql-updates``), consisting only of the characters ``a-z``, |
|
|
177 | ``0-9``, ``+`` (plus), ``:`` (colon), ``-`` (hyphen) and ``_`` (underscore). |
|
|
178 | |
|
|
179 | News Item Directories |
125 | --------------------- |
180 | --------------------- |
126 | |
181 | |
127 | Each news item will be represented by a single text file. This file will be |
182 | Each news item will be represented by a directory whose name is the same as the |
128 | encoded using UTF-8 for compatibility with and for the same reason as existing |
183 | news item's identifier. |
129 | Gentoo documentation [#docs-policy]_ and tree [#glep-31]_ practices. |
|
|
130 | |
184 | |
131 | The news item will be named in the form ``yyyy-mm-dd-item-name.en.txt``, where |
185 | The directory will contain a file named ``yyyy-mm-dd-short-name.en.txt``, which |
132 | ``item-name`` is a very short name (e.g. ``apache-updates``) and ``en`` is the |
186 | contains the text of the news item, in English, in the format described below. |
133 | two letter ISO 639 [#iso-639]_ language code for the news item. The short name |
|
|
134 | must consist only of characters ``a-z``, ``A-Z``, ``0-9`` and ``-`` (hyphen). |
|
|
135 | |
187 | |
136 | News items may be signed using GPG. If this is done, a detached signature should |
188 | If a news item is translated, other files named ``yyyy-mm-dd-short-name.xx.txt`` |
137 | be used. |
189 | (where ``xx`` is the ISO 639 [#iso-639]_ two letter country code) will also be |
|
|
190 | provided. However, only the English version of a news item is authoritative. |
|
|
191 | This anglocentricity is justified by precedent [#glep-34]_. |
138 | |
192 | |
139 | The directory and file name rules are designed specifically to allow easy |
193 | News Item Files |
140 | sorting by date. |
194 | --------------- |
141 | |
195 | |
142 | An English (``en``) version must be available for all news items. Other |
196 | A news item file is a text file, encoded using UTF-8 [#rfc-3629]_ for |
143 | languages may be provided either by the original author or by other translators |
197 | compatibility with and for the same reasons as existing Gentoo documentation |
144 | who have commit access. This anglocentricity is justified on the grounds that |
198 | [#docs-policy]_ and the tree [#glep-31]_. |
145 | nobody objected to it with GLEP 34 [#glep-34]_. |
|
|
146 | |
199 | |
|
|
200 | News items should be signed with a detached GPG signature: :: |
|
|
201 | |
|
|
202 | gpg --armour --detach-sign ????-??-??-*.??.txt |
|
|
203 | |
147 | A news item's content will consist of an RFC 822 [#rfc-822]_ style header |
204 | A news item file's content will consist of an RFC 822 style header [#rfc-822]_ |
148 | followed by the main body of the message as plain text. This GLEP defines |
205 | followed by the main body of the message as plain text. This GLEP defines |
149 | various optional and mandatory headers. Future GLEPs may propose new headers -- |
206 | various optional and mandatory headers. Future GLEPs may propose new headers — |
150 | tools handling these news items must ignore any unrecognised header. |
207 | tools handling these news items must ignore any unrecognised header. |
151 | |
208 | |
152 | News Item Headers |
209 | News Item Headers |
153 | ''''''''''''''''' |
210 | ''''''''''''''''' |
154 | |
211 | |
155 | The following headers describe the purpose and format of the news item: |
212 | The following headers describe the purpose and format of the news item: |
156 | |
213 | |
157 | ``Title:`` |
214 | ``Title:`` |
158 | A short (maximum 44 characters) descriptive title. Mandatory. |
215 | A short (maximum 44 characters) descriptive title. Mandatory. |
|
|
216 | |
159 | ``Author:`` |
217 | ``Author:`` |
160 | Author's name and email address, in the form ``Real Name <email@address>``. |
218 | Author's name and email address, in the form ``Real Name <email@address>``. |
161 | Mandatory, multiple author fields may be specified if appropriate. |
219 | Mandatory; multiple author headers may be specified if appropriate. |
|
|
220 | |
162 | ``Translator:`` |
221 | ``Translator:`` |
163 | For translated news items, the translator's name and email address. |
222 | For translated news items, the translator's name and email address. Multiple |
|
|
223 | translator headers may be specified if appropriate. |
|
|
224 | |
164 | ``Content-Type:`` |
225 | ``Content-Type:`` |
165 | Must be ``text/plain``. Mandatory. |
226 | Must be ``text/plain``. Mandatory. |
|
|
227 | |
166 | ``Posted:`` |
228 | ``Posted:`` |
167 | Date of posting, in ``dd-mmm-yyyy`` format (e.g. 14-Aug-2001). UTC time in |
229 | Date of posting, in ``yyyy-mm-dd`` format (e.g. 2005-12-18) for |
168 | ``hh-mm-ss +0000`` format may also be included. This field is mandatory. |
230 | compatibility with GLEP 45 [#glep-45]_. Mandatory. |
|
|
231 | |
169 | ``Version:`` |
232 | ``Revision:`` |
170 | 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 |
171 | 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 |
172 | file. |
235 | file. Mandatory. |
|
|
236 | |
173 | ``News-Item-Format:`` |
237 | ``News-Item-Format:`` |
174 | Must be ``1.0``. Future revisions to the format may increment the minor |
238 | Must be ``1.0``. Future revisions to the format may increment the minor |
175 | number for backwards-compatible changes, or the major number for major |
239 | number for backwards-compatible changes, or the major number for major |
176 | changes. |
240 | changes. |
177 | |
241 | |
178 | The following headers are used for filtering. If none of these headers are |
242 | The following headers are used for filtering: |
179 | specified, the news item is displayed for all users. Otherwise, the news item is |
|
|
180 | displayed if *at least one* header matches. |
|
|
181 | |
243 | |
182 | ``Display-If-Installed:`` |
244 | ``Display-If-Installed:`` |
183 | A dependency atom or simple package name (for example, |
245 | A dependency atom or simple package name (for example, |
184 | ``<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 |
185 | package specified installed, the news item should be displayed. |
248 | obtained, the news item should be displayed. |
186 | |
249 | |
187 | ``Display-If-Keyword:`` |
250 | ``Display-If-Keyword:`` |
188 | A keyword [#glep-22]_ name, for example ``mips``. If the user is on the arch |
251 | A keyword [#glep-22]_ name, for example ``mips`` or ``x86-fbsd``. If the |
189 | in question, the news item should be displayed. |
252 | user is on the keyword in question, the news item should be displayed. |
190 | |
253 | |
191 | ``Display-If-Profile:`` |
254 | ``Display-If-Profile:`` |
192 | A profile path, for example ``default-linux/sparc/sparc64/server``. If the |
255 | A profile path, for example ``default-linux/sparc/sparc64/server``. If the |
193 | user is using the exact profile in question, the news item should be |
256 | user is using the exact profile in question, or a subprofile of this |
194 | displayed. This header may be used to replace ``deprecated`` files in the |
257 | profile, the news item should be displayed. This header may be used to |
195 | future. |
258 | replace ``deprecated`` files in the future. |
|
|
259 | |
|
|
260 | .. Note:: When performing package moves, developers must also update any |
|
|
261 | relevant ``Display-If-Installed`` headers in news files. |
|
|
262 | |
|
|
263 | The algorithm used to determine whether a news item is 'relevant' is as |
|
|
264 | follows: |
|
|
265 | |
|
|
266 | * For each ``Display-If-`` header type which occurs at least once: |
|
|
267 | |
|
|
268 | + The news item is not relevant if none of the headers of this type are |
|
|
269 | successfully matched. |
|
|
270 | |
|
|
271 | * Otherwise the news item is relevant. |
|
|
272 | |
|
|
273 | In particular, if no ``Display-If-`` header is specified, a news item will be |
|
|
274 | relevant for all users. |
|
|
275 | |
|
|
276 | This algorithm was chosen because it makes conditions like "display this news |
|
|
277 | item for ``YourSQL`` users who are on ``sparc`` or ``x86-obsd`` relatively |
|
|
278 | simple to specify — it is believed that these kinds of condition are far more |
|
|
279 | likely to occur than "display this news item for people using ``YourSQL``, or |
|
|
280 | for people on ``sparc`` or ``x86-obsd``\" or "display these news items for |
|
|
281 | people who use ``YourSQL`` and who are on both ``sparc`` and ``x86-obsd``\". |
196 | |
282 | |
197 | News Item Body |
283 | News Item Body |
198 | '''''''''''''' |
284 | '''''''''''''' |
199 | |
285 | |
200 | The header section must be followed by a blank line, then the main body of the |
286 | The header section must be followed by a blank line, then the main body of the |
201 | text. |
287 | text. |
202 | |
288 | |
203 | The text body should be wrapped at 72 characters. No fancy formatting or tab |
289 | The text body should be wrapped at 72 characters. No fancy formatting or tab |
204 | characters should be used -- the news item may be being displayed directly to a |
290 | characters should be used — the news item may be being displayed directly to a |
205 | terminal. Paragraphs should be separated by two blank lines. |
291 | terminal. Paragraphs should be separated by a blank line. |
206 | |
292 | |
207 | Hyperlinks may be used to refer to further information (for example, an upgrade |
293 | Hyperlinks may be used to refer to further information (for example, an upgrade |
208 | guide). However, the main body of the news item should be descriptive and not |
294 | guide). However, the main body of the news item should be descriptive and not |
209 | simply a "read this link" text. It is assumed that the user will have access to |
295 | simply a "read this link" text. It is assumed that the user will have access to |
210 | a web browser *somewhere*, but not necessarily on the box which is being |
296 | a web browser *somewhere*, but not necessarily on the box which is being |
211 | administrated -- this will be the case on may servers and routers, for example. |
297 | administrated — this will be the case on may servers and routers, for example. |
212 | |
298 | |
213 | Example News Item |
299 | Example News Item |
214 | ''''''''''''''''' |
300 | ''''''''''''''''' |
215 | |
301 | |
216 | The following hypothetical news item could be used for an upgrade to the |
302 | `This hypothetical news item`__ could be used for an upgrade to the |
217 | ``YourSQL`` database format which breaks forward compatibility. It should be |
303 | ``YourSQL`` database format which breaks forward compatibility. |
218 | named ``2005-11/2005-11-01-yoursql-upgrades.en.txt``. |
|
|
219 | |
304 | |
220 | :: |
305 | .. __: glep-0042-extras/example-news-item.txt |
221 | |
|
|
222 | Title: YourSQL Upgrades from 4.0 to 4.1 |
|
|
223 | Author: Ciaran McCreesh <ciaranm@gentoo.org> |
|
|
224 | Content-Type: text/plain |
|
|
225 | Posted: 01-Nov-2005 |
|
|
226 | Display-If-Installed: <dev-db/yoursql-4.1_alpha |
|
|
227 | |
|
|
228 | YourSQL databases created using YourSQL version 4.0 are incompatible |
|
|
229 | with YourSQL version 4.1 or later. There is no reliable way to |
|
|
230 | automate the database format conversion, so action from the system |
|
|
231 | administrator is required before an upgrade can take place. |
|
|
232 | |
|
|
233 | Please see the Gentoo YourSQL Upgrade Guide for instructions: |
|
|
234 | |
|
|
235 | http://www.gentoo.org/doc/en/yoursql-upgrading.xml |
|
|
236 | |
|
|
237 | Also see the official YourSQL documentation: |
|
|
238 | |
|
|
239 | http://dev.yoursql.com/doc/refman/4.1/en/upgrading-from-4-0.html |
|
|
240 | |
|
|
241 | After upgrading, you should also recompile any packages which link |
|
|
242 | against YourSQL: |
|
|
243 | |
|
|
244 | revdep-rebuild --library=libyoursqlclient.so.12 |
|
|
245 | |
|
|
246 | The revdep-rebuild tool is provided by app-portage/gentoolkit. |
|
|
247 | |
306 | |
248 | News Item Quality Control |
307 | News Item Quality Control |
249 | ------------------------- |
308 | ------------------------- |
250 | |
309 | |
251 | There have been complaints regarding the comprehensibility of some upgrade |
310 | There have been complaints regarding the comprehensibility of some upgrade |
252 | notices and news items in the past. This is understandable -- not every Gentoo |
311 | notices and news items in the past. This is understandable — not every Gentoo |
253 | developer speaks English as a first language. However, for the sake of clarity |
312 | developer speaks English as a first language. However, for the sake of clarity, |
254 | and professionalism it is important that any language problems be corrected |
313 | professionalism and avoiding making us look like prats, it is important that any |
255 | before inflicting a news item upon end users. |
314 | language problems be corrected before inflicting a news item upon end users. |
256 | |
315 | |
257 | Thus, all proposed news items must be posted to the ``gentoo-dev`` or |
316 | Thus, at least 72 hours before a proposed news item is committed, it must be |
258 | ``gentoo-core`` mailing list, and ``Cc:``\ed to ``pr@gentoo.org`` at least 72 |
317 | posted to the ``gentoo-dev`` mailing list and ``Cc:``\ed to ``pr@gentoo.org`` |
259 | hours before being committed (exceptions may be made in exceptional |
318 | (exceptions may be made in exceptional circumstances). Any complaints — for |
260 | circumstances). Any complaints regarding wording or clarity **must** be |
319 | example regarding wording, clarity or accuracy — **must** be addressed before |
261 | addressed before the news item goes live. |
320 | the news item goes live. |
|
|
321 | |
|
|
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). |
262 | |
327 | |
263 | News items must only be for **important** changes that may cause serious upgrade |
328 | News items must only be for **important** changes that may cause serious upgrade |
264 | or compatibility problems. Ordinary upgrade messages and non-critical news items |
329 | or compatibility problems. Ordinary upgrade messages and non-critical news items |
265 | should remain in ``einfo`` notices. The importance of the message to its |
330 | should remain in ``einfo`` notices. The importance of the message to its |
266 | intended audience should be justified with the proposal. |
331 | intended audience should be justified with the proposal. |
… | |
… | |
274 | ---------------------- |
339 | ---------------------- |
275 | |
340 | |
276 | Server Side |
341 | Server Side |
277 | ''''''''''' |
342 | ''''''''''' |
278 | |
343 | |
279 | News items are to be made available via the Portage tree. This removes any |
344 | News items are to be made available via the standard rsync tree. This removes |
280 | need for polling of a remote source. |
345 | any need for polling of a remote source. |
281 | |
346 | |
282 | A new repository will be created for news items. The type (CVS or Subversion), |
347 | A new repository will be created for news items. The type (CVS or Subversion), |
283 | location and access controls on this repository are beyond the scope of this |
348 | location and access controls on this repository are beyond the scope of this |
284 | GLEP. |
349 | GLEP. |
285 | |
350 | |
286 | .. Note:: A previous draft of this GLEP instead used the main ``gentoo-x86`` |
351 | .. Note:: A previous draft of this GLEP instead used the main ``gentoo-x86`` |
287 | tree. This was changed following advice from Infrastructure |
352 | tree. This was changed following advice from Infrastructure |
288 | [#ramereth-repo]_. Both solutions have the same end result. |
353 | [#ramereth-repo]_. Both solutions have the same end result. |
289 | |
354 | |
290 | This repository will contain directories named ``yyyy-mm/``, where ``yyyy`` is |
355 | This repository will contain directories named ``yyyy/mm/``, where ``yyyy`` is |
291 | the current year and ``mm`` is the current month number (01 for January through |
356 | the current year and ``mm`` is the current month number (01 for January through |
292 | 12 for December). This separation will help keep news items more manageable. |
357 | 12 for December). This separation will help keep news items more manageable. |
293 | |
358 | |
294 | The contents of this repository will automatically be merged with the main rsync |
359 | The contents of this repository will automatically be merged with the main rsync |
295 | tree, placing the items under a top-level ``news/`` directory. The method used |
360 | tree, placing the items in a ``metadata/news/`` directory. The method used for |
296 | for merging these items is beyond the scope of this GLEP -- a similar setup is |
361 | merging these items is beyond the scope of this GLEP — a similar setup is |
297 | already used for merging GLSAs into the rsync tree. |
362 | already used for merging GLSAs into the rsync tree. |
298 | |
363 | |
299 | .. Note:: The ``profiles/`` directory will *not* be used. This fits in with |
364 | The main rsync tree will **not** use the ``yyyy/mm/`` subdirectory layout. |
300 | the Portage team's future plans for ``profiles/`` and ``metadata/`` |
|
|
301 | separation. |
|
|
302 | |
365 | |
303 | Client Side |
366 | Client Side |
304 | ''''''''''' |
367 | ''''''''''' |
305 | |
368 | |
306 | Whenever relevant unread news items are found, ``emerge`` will copy or symlink |
369 | Whenever relevant unread news items are found, the package manager will create a |
307 | the news file into ``/var/lib/gentoo/news/``. |
370 | file named ``/var/lib/gentoo/news/news-repoid.unread`` (if it does not |
|
|
371 | already exist) and append the news item identifier (eg |
|
|
372 | ``2005-11-01-yoursql-updates``) on a new line. |
308 | |
373 | |
309 | Notification that new relevant news items will be displayed via the |
374 | Notification that new relevant news items will be displayed via the |
310 | ``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 |
311 | updating" messages: |
376 | updating" messages: |
312 | |
377 | |
313 | :: |
378 | :: |
314 | |
379 | |
315 | * Important: 3 config files in /etc need updating. |
|
|
316 | * Type emerge --help config to learn how to update config files. |
|
|
317 | |
|
|
318 | * Important: there are 5 unread news items. |
380 | * Important: there are 5 unread news items. |
319 | * Type emerge --help news to learn how to read news files. |
381 | * Type emerge --help news to learn how to read news files. |
320 | |
382 | |
321 | The unread news message will also be displayed immediately after an |
383 | Checks for new news messages should be displayed: |
322 | ``emerge sync``. |
|
|
323 | |
384 | |
324 | Portage may also warn of unread news items using, for example, a red flashy |
385 | * After an ``emerge sync`` |
325 | before actions such as merging a package. |
386 | * After an ``emerge --pretend`` |
|
|
387 | * Before an ``emerge <target>`` (which may also include a red warning message) |
|
|
388 | * Before an ``emerge --ask <target>`` sequence |
326 | |
389 | |
327 | Portage must keep track of news items which have already been installed to avoid |
390 | The package manager may use a timestamp check file to avoid having to process |
328 | repeatedly reinstalling a deleted news item. |
391 | news items unnecessarily. |
|
|
392 | |
|
|
393 | The package manager must keep track of news items that have already been added |
|
|
394 | to the unread list to avoid repeatedly marking a deleted news item. This could |
|
|
395 | be handled via a ``news-repoid.skip`` file containing the IDs of news items that |
|
|
396 | have already been added to a ``news-repoid.unread`` file, but this method is not |
|
|
397 | required by this GLEP. |
329 | |
398 | |
330 | Users who really don't care about news items can use ``rsync_excludes`` to |
399 | Users who really don't care about news items can use ``rsync_excludes`` to |
331 | filter out the ``news/`` directory. |
400 | filter out the ``metadata/news/`` directory. |
332 | |
401 | |
333 | News Item Clients |
402 | News Item Clients |
334 | ----------------- |
403 | ----------------- |
335 | |
404 | |
336 | Once a news item is 'installed', third party tools (or a traditional Unix pager |
405 | Once a news item is marked for reading, third party tools (or traditional core |
337 | and ``rm``) can be used to display and view the news files. An ``eselect`` |
406 | Unix tools) can be used to display and view the news files. |
|
|
407 | |
|
|
408 | When a news item is read, its name should be removed from the |
|
|
409 | ``news-repoid.unread`` file. If a news client acts as an interactive reader |
|
|
410 | rather than a gateway, it should then add the name to a ``news-repoid.read`` |
|
|
411 | file in the same directory with the same file format. |
|
|
412 | |
338 | [#eselect]_ module shall be created as the 'suggested' display tool; other |
413 | An ``eselect`` [#eselect]_ module shall be created as the 'suggested' display |
339 | display tools (for example, a news to email forwarder, which would be ideal for |
414 | tool; other display tools (for example, a news to email forwarder, which would |
340 | users who sync on a cron) are left as options for those who desire them -- the |
415 | be ideal for users who sync on a ``cron``) are left as options for those who |
341 | simple file format make this relatively simple. |
416 | desire them. |
342 | |
417 | |
343 | News Item Removal |
418 | News Item Removal |
344 | ----------------- |
419 | ----------------- |
345 | |
420 | |
346 | News items can be removed (by removing the news file from the main tree) when |
421 | News items can be removed (by removing the news file from the main tree) when |
… | |
… | |
349 | entries. |
424 | entries. |
350 | |
425 | |
351 | Integration with Existing Systems |
426 | Integration with Existing Systems |
352 | ================================= |
427 | ================================= |
353 | |
428 | |
354 | It would be trivial to convert these news items into the format used for news |
429 | It would be simple to convert these news items into the format used for news |
355 | items on the Gentoo website or posts for the ``gentoo-announce`` mailing list. |
430 | items on the Gentoo website or posts for the ``gentoo-announce`` mailing list. |
356 | |
431 | |
357 | There is an existing automated tool [#forums-glsa]_ for posting GLSAs to the |
432 | There is an existing automated tool [#forums-glsa]_ for posting GLSAs to the |
358 | forums. A similar tool can be used for these news items. |
433 | forums. A similar tool can be used for these news items. |
359 | |
434 | |
… | |
… | |
372 | TODO |
447 | TODO |
373 | |
448 | |
374 | Simple ``eselect`` News Client |
449 | Simple ``eselect`` News Client |
375 | ------------------------------ |
450 | ------------------------------ |
376 | |
451 | |
377 | A demonstration ``eselect`` news display script follows: |
452 | TODO Removed until the exact format details are figured out. |
378 | |
|
|
379 | :: |
|
|
380 | |
|
|
381 | # Copyright 1999-2005 Gentoo Foundation |
|
|
382 | # Distributed under the terms of the GNU General Public License v2 |
|
|
383 | # $Id: glep-0042.txt,v 1.1 2005/11/05 03:32:09 g2boojum Exp $ |
|
|
384 | |
|
|
385 | DESCRIPTION="Read important Gentoo news items" |
|
|
386 | MAINTAINER="ciaranm@gentoo.org" |
|
|
387 | SVN_DATE='$Date: 2005/11/05 03:32:09 $' |
|
|
388 | VERSION=$(svn_date_to_version "${SVN_DATE}" ) |
|
|
389 | |
|
|
390 | get_news_item_list() { |
|
|
391 | [[ -d "${ROOT}/var/lib/gentoo/news" ]] || return |
|
|
392 | ( |
|
|
393 | local news |
|
|
394 | for news in "${ROOT}/var/lib/gentoo/news/"*.txt ; do |
|
|
395 | echo $(basename ${news%%.*} ) |
|
|
396 | done |
|
|
397 | ) | sort -u |
|
|
398 | } |
|
|
399 | |
|
|
400 | get_filename() { |
|
|
401 | local best_lang=${LANG%%_*} lang= filename="${1}" |
|
|
402 | [[ -e "/${filename}" ]] || for lang in "${best_lang}" "en" ; do |
|
|
403 | filename="${ROOT}/var/lib/gentoo/news/${1}.${lang}.txt" |
|
|
404 | [[ -e "${filename}" ]] && break |
|
|
405 | done |
|
|
406 | [[ -e "${filename}" ]] && echo "${filename}" || die -q "Can't find '${1}'" |
|
|
407 | } |
|
|
408 | |
|
|
409 | get_all_filenames() { |
|
|
410 | if [[ -z "${1}" ]] ; then |
|
|
411 | echo "${ROOT}/var/lib/gentoo/news/"*.??".txt" |
|
|
412 | else |
|
|
413 | echo "${ROOT}/var/lib/gentoo/news/${1}."??".txt" |
|
|
414 | fi |
|
|
415 | } |
|
|
416 | |
|
|
417 | get_headers() { |
|
|
418 | sed -e '/^$/Q' < $(get_filename "${1}" ) |
|
|
419 | } |
|
|
420 | |
|
|
421 | get_body() { |
|
|
422 | sed -e '1,/^$/d' < $(get_filename "${1}" ) |
|
|
423 | } |
|
|
424 | |
|
|
425 | get_title() { |
|
|
426 | get_headers "${1}" | sed -n -e '/^[Tt]itle: /s/^[^:]\+:[ \t]*//p' |
|
|
427 | } |
|
|
428 | |
|
|
429 | ### list action |
|
|
430 | |
|
|
431 | ## {{{ list stuff |
|
|
432 | describe_list() { |
|
|
433 | echo "List available news items" |
|
|
434 | } |
|
|
435 | |
|
|
436 | do_list() { |
|
|
437 | write_list_start "Available news items:" |
|
|
438 | local empty=yes n=1 |
|
|
439 | for news in $(get_news_item_list ) ; do |
|
|
440 | write_numbered_list_entry ${n} "$(highlight $(get_title ${news} ) ) (${news})" |
|
|
441 | n=$(( n + 1 )) |
|
|
442 | done |
|
|
443 | } |
|
|
444 | ## }}} |
|
|
445 | |
|
|
446 | ## {{{ show stuff |
|
|
447 | describe_show(){ |
|
|
448 | echo "Show a news item" |
|
|
449 | } |
|
|
450 | |
|
|
451 | do_show() { |
|
|
452 | [[ -z "${1}" ]] && die -q "You didn't tell me which news item to read" |
|
|
453 | |
|
|
454 | local target=${1} filename= |
|
|
455 | if is_number "${target}" && [[ ${target} -ge 1 ]] ; then |
|
|
456 | targets=( $(get_news_item_list ) ) |
|
|
457 | target=${targets[$(( ${target} - 1 ))]} |
|
|
458 | fi |
|
|
459 | |
|
|
460 | ( |
|
|
461 | get_headers "${target}" | grep -v '^Display-If-\|Content-Type:' |
|
|
462 | echo |
|
|
463 | get_body "${target}" |
|
|
464 | ) | ${PAGER:-cat} |
|
|
465 | } |
|
|
466 | ## }}} |
|
|
467 | |
|
|
468 | # {{{ delete stuff |
|
|
469 | describe_delete() { |
|
|
470 | echo "Delete a news item" |
|
|
471 | } |
|
|
472 | |
|
|
473 | do_delete() { |
|
|
474 | [[ -z "${1}" ]] && die -q "You didn't tell me which news item to delete" |
|
|
475 | |
|
|
476 | for target in $@ ; do |
|
|
477 | if is_number "${target}" && [[ ${target} -ge 1 ]] ; then |
|
|
478 | targets=( $(get_news_item_list ) ) |
|
|
479 | target=${targets[$(( ${target} - 1 ))]} |
|
|
480 | fi |
|
|
481 | |
|
|
482 | rm $(get_all_filenames "${target}" ) || die -q "Couldn't delete ${target}" |
|
|
483 | done |
|
|
484 | } |
|
|
485 | # }}} |
|
|
486 | |
|
|
487 | # {{{ delete-all |
|
|
488 | describe_delete-all() { |
|
|
489 | echo "Delete all news items" |
|
|
490 | } |
|
|
491 | |
|
|
492 | do_delete-all() { |
|
|
493 | rm $(get_all_filenames ) || die -q "Couldn't delete news items" |
|
|
494 | } |
|
|
495 | # }}} |
|
|
496 | |
453 | |
497 | Simple News to Mail Forwarder |
454 | Simple News to Mail Forwarder |
498 | ----------------------------- |
455 | ----------------------------- |
499 | |
456 | |
500 | A demonstration shell script which delivers news items via email follows: |
457 | TODO Removed until the exact format details are figured out. |
501 | |
|
|
502 | :: |
|
|
503 | |
|
|
504 | #!/bin/bash |
|
|
505 | |
|
|
506 | to_address="root@localhost" |
|
|
507 | mail="mailx" |
|
|
508 | best_lang="${LANG%%_*}" |
|
|
509 | |
|
|
510 | for news in /var/lib/gentoo/news/*.*.txt ; do |
|
|
511 | [[ -z "${best_lang}" ]] || news="${news%%.*}.${best_lang}.txt" |
|
|
512 | [[ -f "${news}" ]] || news="${news%%.*}.en.txt" |
|
|
513 | [[ -f "${news}" ]] || continue |
|
|
514 | title=$(sed -n -e '/^Title:/ { s,^[^:]\+:[ \t]\+,,p ; q }' < ${news} ) |
|
|
515 | sed -e '1,/^$/ { /^Display-If\|Content-Type/d }' < "${news}" | \ |
|
|
516 | ${mail} -s "Gentoo news: ${title}" "${to_address}" && \ |
|
|
517 | for file in ${news%%.*}.*.txt ; do rm "${file}" ; done |
|
|
518 | done |
|
|
519 | |
458 | |
520 | Credits |
459 | Credits |
521 | ======= |
460 | ======= |
522 | |
461 | |
523 | The idea behind notifying users of news updates via Portage comes from Stuart |
462 | The idea behind notifying users of news updates via Portage comes from Stuart |
524 | Herbert [#stuart-blog]_. |
463 | Herbert [#stuart-blog]_. |
525 | |
464 | |
526 | Thanks to Lance Albertson, Donnie Berkholz, Grant Goodyear, Brian Harring, Dan |
465 | Thanks to Lance Albertson, Stephen Bennett, Donnie Berkholz, Grant Goodyear, |
527 | Meltzer, Paul de Vrieze and Alec Warner for input. Some of the ideas presented |
466 | Brian Harring, Dan Meltzer, Jason Stubbs, Paul de Vrieze and Alec Warner for |
528 | here are theirs, others go completely against their suggestions. |
467 | input. Some of the ideas presented here are theirs, others go completely |
|
|
468 | against their suggestions. |
|
|
469 | |
|
|
470 | Example Files |
|
|
471 | ============= |
|
|
472 | |
|
|
473 | TODO Removed until the exact format details are figured out. |
529 | |
474 | |
530 | References |
475 | References |
531 | ========== |
476 | ========== |
532 | |
477 | |
|
|
478 | .. [#bug-11359] Bugzilla Bug 11359 |
|
|
479 | "[NEW FEATURE] pkg_postinst/pkg_preinst ewarn/einfo logging", |
|
|
480 | https://bugs.gentoo.org/show_bug.cgi?id=11359 |
533 | .. [#docs-policy] Gentoo XML Guide, Daniel Robbins et al., |
481 | .. [#docs-policy] Gentoo XML Guide, Daniel Robbins et al., |
534 | http://www.gentoo.org/doc/en/xml-guide.xml |
482 | http://www.gentoo.org/doc/en/xml-guide.xml |
535 | .. [#eselect] eselect modular framework for configuration and |
483 | .. [#eselect] eselect modular framework for configuration and |
536 | administration utilities, |
484 | administration utilities, |
537 | http://www.gentoo.org/proj/en/eselect/index.xml |
485 | http://www.gentoo.org/proj/en/eselect/index.xml |
538 | .. [#forums-glsa] Forums user GLSA, |
486 | .. [#forums-glsa] Forums user GLSA, |
539 | http://forums.gentoo.org/profile.php?mode=viewprofile&u=55648 |
487 | http://forums.gentoo.org/profile.php?mode=viewprofile&u=55648 |
540 | .. [#forums-whining] Forums thread "Gentoo Apache2 Config Change Idiocy", |
488 | .. [#forums-apache2] Forums thread "Gentoo Apache2 Config Change Idiocy", |
541 | http://forums.gentoo.org/viewtopic-t-384368.html |
489 | http://forums.gentoo.org/viewtopic-t-384368.html |
542 | .. [#glep-22] GLEP 22: "New "keyword" system to incorporate various |
490 | .. [#glep-22] GLEP 22: "New "keyword" system to incorporate various |
543 | userlands/kernels/archs", Grant Goodyear, |
491 | userlands/kernels/archs", Grant Goodyear, |
544 | http://www.gentoo.org/proj/en/glep/glep-0022.html |
492 | http://www.gentoo.org/proj/en/glep/glep-0022.html |
545 | .. [#glep-31] GLEP 31: "Character Sets for Portage Tree Items", Ciaran |
493 | .. [#glep-31] GLEP 31: "Character Sets for Portage Tree Items", Ciaran |
… | |
… | |
548 | .. [#glep-34] GLEP 34: "Per-Category metadata.xml Files", Ciaran McCreesh, |
496 | .. [#glep-34] GLEP 34: "Per-Category metadata.xml Files", Ciaran McCreesh, |
549 | http://www.gentoo.org/proj/en/glep/glep-0034.html |
497 | http://www.gentoo.org/proj/en/glep/glep-0034.html |
550 | .. [#glep-36] GLEP 36: "Subversion/CVS for Gentoo Hosted Projects", Aaron |
498 | .. [#glep-36] GLEP 36: "Subversion/CVS for Gentoo Hosted Projects", Aaron |
551 | Walker, |
499 | Walker, |
552 | 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 |
553 | .. [#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" |
554 | .. [#ramereth-repo] "Re: [gentoo-dev] GLEP ??: Critical News Reporting", Lance |
504 | .. [#ramereth-repo] "Re: [gentoo-dev] GLEP ??: Critical News Reporting", Lance |
555 | Albertson, |
505 | Albertson, |
556 | http://marc.theaimsgroup.com/?l=gentoo-dev&m=113111585907703&w=2 |
506 | http://marc.theaimsgroup.com/?l=gentoo-dev&m=113111585907703&w=2 |
557 | .. [#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" |
|
|
508 | .. [#rfc-3629] RFC 3629: "UTF-8, a transformation format of ISO 10646" |
|
|
509 | http://www.ietf.org/rfc/rfc3629.txt |
558 | .. [#stuart-blog] "Favouring an automatic news mechanism", Stuart Herbert, |
510 | .. [#stuart-blog] "Favouring an automatic news mechanism", Stuart Herbert, |
559 | http://stu.gnqs.org/diary/gentoo.php/2005/10/28/favouring_an_automatic_news_mechanism |
511 | http://stu.gnqs.org/diary/gentoo.php/2005/10/28/favouring_an_automatic_news_mechanism |
560 | |
512 | |
561 | Copyright |
513 | Copyright |
562 | ========= |
514 | ========= |