Re: [gentoo-dev] GLEP 42 "Critical News Reporting" Round Two

[Ciaran McCreesh <ciaranm@gentoo.org>]

[-- Attachment #1: Type: text/plain, Size: 9081 bytes --]

On Sat, 05 Nov 2005 11:28:33 +0100 Grobian <grobian@gentoo.org> 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@address>``. 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
| > ``pr@gentoo.org`` 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


[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]