1 |
On Sat, 05 Nov 2005 11:28:33 +0100 Grobian <grobian@g.o> wrote: |
2 |
| > Preemptive |
3 |
| > Users should be told of changes *before* they break the user's |
4 |
| > system, after the damage has already been done. |
5 |
| |
6 |
| style suggestion for unambigous interpretation: |
7 |
| perhaps a "because if applied afterwards" instead of "after" |
8 |
|
9 |
Ugh. Wonder how many comments I'm going to get on that one... There |
10 |
should be a "not" before "system", which I accidentally killed by |
11 |
pressing the wrong key in Vim. |
12 |
|
13 |
| Apart from that this point seems to repeat much of the previous one, |
14 |
| it introduces a new unfounded claim (users do read, but now too late) |
15 |
|
16 |
Read the linked forums thread and all will become clear. |
17 |
|
18 |
| > Lightweight |
19 |
| > It is not reasonable to expect all users to have an MTA, web |
20 |
| > browser, email client, cron daemon or text processing suite |
21 |
| > available on their system. |
22 |
| |
23 |
| Direct question that follows from this: what *do* we expect a |
24 |
| user/system to have available? I think it's good to state that as |
25 |
| well, since you're excluding a lot here in once sentence. |
26 |
|
27 |
Anything that's in the system target, and as little as is reasonably |
28 |
possible extra. |
29 |
|
30 |
| Where does point 4 differ from the second part of point 3? |
31 |
|
32 |
Oops. |
33 |
|
34 |
| > 6. Portage filters the news item and, if it is relevant, installs |
35 |
| > it in a special location to be read by a news item reader. Messages |
36 |
| > are also displayed to inform the user that news is available. |
37 |
| |
38 |
| So, same as for point 5, the exact details on how this works and what |
39 |
| a 'news item reader' is (since you previously defined a requirement |
40 |
| of having almost nothing available on the system) should be refered |
41 |
| to here. I want to be sure that you will elaborate on it lateron, so |
42 |
| I can stack up my many questions for now. |
43 |
|
44 |
A news item reader is something which reads news items. |
45 |
|
46 |
| > The news item will be named in the form |
47 |
| > ``yyyy-mm-dd-item-name.en.txt``, where ``item-name`` is a very |
48 |
| > short name (e.g. ``apache-updates``) and ``en`` is the two letter |
49 |
| > ISO 639 [#iso-639]_ language code for the news item. The short name |
50 |
| > must consist only of characters ``a-z``, ``A-Z``, ``0-9`` and ``-`` |
51 |
| > (hyphen). |
52 |
| |
53 |
| Consider replacing hyphen with an underscore to ease parsing. |
54 |
|
55 |
Mixing hyphens and underscores? That's just going to start confusing |
56 |
things... |
57 |
|
58 |
| (Maybe: "An English (''en'') version must be available for all news |
59 |
| items as per GLEP 34 [#glep-34]_. Other languages ...") |
60 |
|
61 |
GLEP 34 doesn't say anything about news items... |
62 |
|
63 |
| > ``Author:`` |
64 |
| > Author's name and email address, in the form ``Real Name |
65 |
| > <email@address>``. Mandatory, multiple author fields may be |
66 |
| > specified if appropriate. |
67 |
| |
68 |
| Separated how? Using commas, semicolons, spaces or whatever? |
69 |
|
70 |
Multiple fields. Maybe that'd be clearer were it to say "Mandatory; |
71 |
multiple author headers may ...". |
72 |
|
73 |
| > ``Version:`` |
74 |
| > Initially 1. Incremented every time a non-trivial change is |
75 |
| > made. Changes which require a re-read of the news item should |
76 |
| > instead use a new news item file. |
77 |
| |
78 |
| Perhaps you want to track trivial changes as well in the minor, in |
79 |
| order to be able to quickly see a change was made, and prevent people |
80 |
| from considering a non-trivial change as trivial. |
81 |
|
82 |
Well, if you want to see that it was made, it's not trivial. |
83 |
|
84 |
| Maybe you should explicitly state this field is optional and why. I |
85 |
| could think of some reasons why this header should be mandatory, but |
86 |
| perhaps you add a completely different value to the header than I do |
87 |
| now. |
88 |
|
89 |
Maybe I should just mark it as mandatory instead. |
90 |
|
91 |
| From a completeness perspective, it would perhaps be a option to |
92 |
| include a special header that contains a boolean expression that |
93 |
| resolves to true if the message is relevant to the user, and false |
94 |
| otherwise. This would allow AND and NOT to be included instead of |
95 |
| only OR semantics. |
96 |
| |
97 |
| In any case, elaborate on why supporting only OR was chosen and why |
98 |
| other (probably investigated) options were discarded (and hence make |
99 |
| my statement above unnecessary). |
100 |
|
101 |
The previous draft had an option for and or none-of modes. I took it |
102 |
out because I don't think it's going to be anywhere near as useful as |
103 |
one might initially think. |
104 |
|
105 |
| > The text body should be wrapped at 72 characters. No fancy |
106 |
| > formatting or tab characters should be used -- the news item may be |
107 |
| > being displayed directly to a terminal. Paragraphs should be |
108 |
| > separated by two blank lines. |
109 |
| |
110 |
| Elaborate some more on "No fancy formatting or tab characters". |
111 |
| People might want/like to include a bulleted/numbered list or insert |
112 |
| a small (shell) code example. Also make some note on the average |
113 |
| length (number of paragraphs) and perhaps a predefined structure |
114 |
| (ie.: introduction/abstract, impact, solutions/actions, |
115 |
| links/more-information) |
116 |
|
117 |
These're things to be decided when news items are sent for review. Once |
118 |
we have some real material there'll be a more useful way of judging |
119 |
what is acceptable and what has gone too far. |
120 |
|
121 |
| > Thus, all proposed news items must be posted to the ``gentoo-dev`` |
122 |
| > or ``gentoo-core`` mailing list, and ``Cc:``\ed to |
123 |
| > ``pr@g.o`` at least 72 hours before being committed |
124 |
| > (exceptions may be made in exceptional circumstances). Any |
125 |
| > complaints regarding wording or clarity **must** be addressed |
126 |
| > before the news item goes live. |
127 |
| |
128 |
| The idea is great, but perhaps the current docs teams should deal |
129 |
| with this, as they are currently responsible for the webpages as well? |
130 |
|
131 |
There's nothing saying "don't Cc: the docs people". By all means Cc: |
132 |
them if they are relevant... |
133 |
|
134 |
| In any case: |
135 |
| - 72 hours is a lot (is there a way to shorten it when everything is |
136 |
| there?) |
137 |
|
138 |
For a major change? If you don't have a major change planned out at |
139 |
least 72 hours in advance you shouldn't be making it. |
140 |
|
141 |
| - what if noone feels like commenting on the submission? |
142 |
|
143 |
Then it's assumed correct. |
144 |
|
145 |
| - how do you know a certain dev is a competent English speaker? |
146 |
|
147 |
*shrug* If we ever get onto linguistics arguments, there're enough of |
148 |
us with copies of Fowler and the OUP Style Guide to settle things. |
149 |
|
150 |
| This raises many questions. I suggest to define the process a bit |
151 |
| more and include a scheme that deals with this kind of concerns to |
152 |
| actually make it water (and fool) proof. |
153 |
|
154 |
Pfff, no system is fool proof. All adding more tricky little items will |
155 |
do is piss people off. |
156 |
|
157 |
| > News items must only be for **important** changes that may cause |
158 |
| > serious upgrade or compatibility problems. Ordinary upgrade |
159 |
| > messages and non-critical news items should remain in ``einfo`` |
160 |
| > notices. The importance of the message to its intended audience |
161 |
| > should be justified with the proposal. |
162 |
| |
163 |
| Somehow there needs to be a voting/selection process to figure out |
164 |
| whether something is **important** or not. |
165 |
|
166 |
It's important if you can justify it as such on -dev. |
167 |
|
168 |
| Does portage only 'warn' and still continue, or does it completely |
169 |
| stop when an unread news item is found for a package that is to be |
170 |
| upgraded? In the first case, the 'preemptive' requirement is being |
171 |
| violated, in the latter, the option for a '--force' or something must |
172 |
| be discussed. (Users with multiple systems might already know the |
173 |
| message, or users might not be interested in it since they don't run |
174 |
| the application in production.) |
175 |
|
176 |
Portage only *warns* you if you try to unmerge glibc... |
177 |
|
178 |
| This Section is too short in this form to live on its own. It should |
179 |
| either be extended or merged with text above where I made a comment |
180 |
| on the details. Perhaps you can elaborate on how to implement such |
181 |
| forwarders, especially in the light of my comments on the previous |
182 |
| Section. |
183 |
|
184 |
See "Reference Implementation". |
185 |
|
186 |
| This sounds much alike what 'mail' used to (and still) does. It has |
187 |
| the ability to see which messages are waiting, select them to read |
188 |
| with a pager and delete them. Make sure you explain why this is |
189 |
| better, and why you 'seemingly' reinvent the wheel here. I think I |
190 |
| can think of some reasons, but I think you need to make it clear. |
191 |
|
192 |
It's vaguely like mail, but without the MTA requirement. |
193 |
|
194 |
| Yes, and make it a requirement that all news messages get posted |
195 |
| somewhere on public channels. |
196 |
|
197 |
I don't see any particular need to *require* that all news items are |
198 |
posted to a specific place. |
199 |
|
200 |
| I hope I have not created a new opportunity for large flame wars. I |
201 |
| tried being quite constructive, and reviewed the GLEP as a scientific |
202 |
| paper. |
203 |
|
204 |
It's a technical paper rather than a scientific one, so I'm not |
205 |
bothering to justify things that every developer should already know. |
206 |
It's mostly a question of space... I *could* bog everyone down in |
207 |
twenty pages of references, but why bother? |
208 |
|
209 |
-- |
210 |
Ciaran McCreesh : Gentoo Developer (Anti-XML, anti-newbie conspiracy) |
211 |
Mail : ciaranm at gentoo.org |
212 |
Web : http://dev.gentoo.org/~ciaranm |