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