On Sat, 05 Nov 2005 11:28:33 +0100 Grobian <[EMAIL PROTECTED]> wrote: | > Preemptive | > Users should be told of changes *before* they break the user's | > system, after the damage has already been done. | | style suggestion for unambigous interpretation: | perhaps a "because if applied afterwards" instead of "after"
Ugh. Wonder how many comments I'm going to get on that one... There
should be a "not" before "system", which I accidentally killed by
pressing the wrong key in Vim.
| Apart from that this point seems to repeat much of the previous one,
| it introduces a new unfounded claim (users do read, but now too late)
Read the linked forums thread and all will become clear.
| > Lightweight
| > It is not reasonable to expect all users to have an MTA, web
| > browser, email client, cron daemon or text processing suite
| > available on their system.
|
| Direct question that follows from this: what *do* we expect a
| user/system to have available? I think it's good to state that as
| well, since you're excluding a lot here in once sentence.
Anything that's in the system target, and as little as is reasonably
possible extra.
| Where does point 4 differ from the second part of point 3?
Oops.
| > 6. Portage filters the news item and, if it is relevant, installs
| > it in a special location to be read by a news item reader. Messages
| > are also displayed to inform the user that news is available.
|
| So, same as for point 5, the exact details on how this works and what
| a 'news item reader' is (since you previously defined a requirement
| of having almost nothing available on the system) should be refered
| to here. I want to be sure that you will elaborate on it lateron, so
| I can stack up my many questions for now.
A news item reader is something which reads news items.
| > The news item will be named in the form
| > ``yyyy-mm-dd-item-name.en.txt``, where ``item-name`` is a very
| > short name (e.g. ``apache-updates``) and ``en`` is the two letter
| > ISO 639 [#iso-639]_ language code for the news item. The short name
| > must consist only of characters ``a-z``, ``A-Z``, ``0-9`` and ``-``
| > (hyphen).
|
| Consider replacing hyphen with an underscore to ease parsing.
Mixing hyphens and underscores? That's just going to start confusing
things...
| (Maybe: "An English (''en'') version must be available for all news
| items as per GLEP 34 [#glep-34]_. Other languages ...")
GLEP 34 doesn't say anything about news items...
| > ``Author:``
| > Author's name and email address, in the form ``Real Name
| > <[EMAIL PROTECTED]>``. Mandatory, multiple author fields may be
| > specified if appropriate.
|
| Separated how? Using commas, semicolons, spaces or whatever?
Multiple fields. Maybe that'd be clearer were it to say "Mandatory;
multiple author headers may ...".
| > ``Version:``
| > Initially 1. Incremented every time a non-trivial change is
| > made. Changes which require a re-read of the news item should
| > instead use a new news item file.
|
| Perhaps you want to track trivial changes as well in the minor, in
| order to be able to quickly see a change was made, and prevent people
| from considering a non-trivial change as trivial.
Well, if you want to see that it was made, it's not trivial.
| Maybe you should explicitly state this field is optional and why. I
| could think of some reasons why this header should be mandatory, but
| perhaps you add a completely different value to the header than I do
| now.
Maybe I should just mark it as mandatory instead.
| From a completeness perspective, it would perhaps be a option to
| include a special header that contains a boolean expression that
| resolves to true if the message is relevant to the user, and false
| otherwise. This would allow AND and NOT to be included instead of
| only OR semantics.
|
| In any case, elaborate on why supporting only OR was chosen and why
| other (probably investigated) options were discarded (and hence make
| my statement above unnecessary).
The previous draft had an option for and or none-of modes. I took it
out because I don't think it's going to be anywhere near as useful as
one might initially think.
| > The text body should be wrapped at 72 characters. No fancy
| > formatting or tab characters should be used -- the news item may be
| > being displayed directly to a terminal. Paragraphs should be
| > separated by two blank lines.
|
| Elaborate some more on "No fancy formatting or tab characters".
| People might want/like to include a bulleted/numbered list or insert
| a small (shell) code example. Also make some note on the average
| length (number of paragraphs) and perhaps a predefined structure
| (ie.: introduction/abstract, impact, solutions/actions,
| links/more-information)
These're things to be decided when news items are sent for review. Once
we have some real material there'll be a more useful way of judging
what is acceptable and what has gone too far.
| > Thus, all proposed news items must be posted to the ``gentoo-dev``
| > or ``gentoo-core`` mailing list, and ``Cc:``\ed to
| > [EMAIL PROTECTED] at least 72 hours before being committed
| > (exceptions may be made in exceptional circumstances). Any
| > complaints regarding wording or clarity **must** be addressed
| > before the news item goes live.
|
| The idea is great, but perhaps the current docs teams should deal
| with this, as they are currently responsible for the webpages as well?
There's nothing saying "don't Cc: the docs people". By all means Cc:
them if they are relevant...
| In any case:
| - 72 hours is a lot (is there a way to shorten it when everything is
| there?)
For a major change? If you don't have a major change planned out at
least 72 hours in advance you shouldn't be making it.
| - what if noone feels like commenting on the submission?
Then it's assumed correct.
| - how do you know a certain dev is a competent English speaker?
*shrug* If we ever get onto linguistics arguments, there're enough of
us with copies of Fowler and the OUP Style Guide to settle things.
| This raises many questions. I suggest to define the process a bit
| more and include a scheme that deals with this kind of concerns to
| actually make it water (and fool) proof.
Pfff, no system is fool proof. All adding more tricky little items will
do is piss people off.
| > News items must only be for **important** changes that may cause
| > serious upgrade or compatibility problems. Ordinary upgrade
| > messages and non-critical news items should remain in ``einfo``
| > notices. The importance of the message to its intended audience
| > should be justified with the proposal.
|
| Somehow there needs to be a voting/selection process to figure out
| whether something is **important** or not.
It's important if you can justify it as such on -dev.
| Does portage only 'warn' and still continue, or does it completely
| stop when an unread news item is found for a package that is to be
| upgraded? In the first case, the 'preemptive' requirement is being
| violated, in the latter, the option for a '--force' or something must
| be discussed. (Users with multiple systems might already know the
| message, or users might not be interested in it since they don't run
| the application in production.)
Portage only *warns* you if you try to unmerge glibc...
| This Section is too short in this form to live on its own. It should
| either be extended or merged with text above where I made a comment
| on the details. Perhaps you can elaborate on how to implement such
| forwarders, especially in the light of my comments on the previous
| Section.
See "Reference Implementation".
| This sounds much alike what 'mail' used to (and still) does. It has
| the ability to see which messages are waiting, select them to read
| with a pager and delete them. Make sure you explain why this is
| better, and why you 'seemingly' reinvent the wheel here. I think I
| can think of some reasons, but I think you need to make it clear.
It's vaguely like mail, but without the MTA requirement.
| Yes, and make it a requirement that all news messages get posted
| somewhere on public channels.
I don't see any particular need to *require* that all news items are
posted to a specific place.
| I hope I have not created a new opportunity for large flame wars. I
| tried being quite constructive, and reviewed the GLEP as a scientific
| paper.
It's a technical paper rather than a scientific one, so I'm not
bothering to justify things that every developer should already know.
It's mostly a question of space... I *could* bog everyone down in
twenty pages of references, but why bother?
--
Ciaran McCreesh : Gentoo Developer (Anti-XML, anti-newbie conspiracy)
Mail : ciaranm at gentoo.org
Web : http://dev.gentoo.org/~ciaranm
pgpJiHQifOwND.pgp
Description: PGP signature
