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

[Grobian]

Ciaran McCreesh wrote:
> Motivation
> ==========
>
> There are currently several ways of getting news out to our users, none of them
> particularly effective:

This assumes the following ways are really ineffective, something which 
you don't prove or give any reason for.  Hence it's eligable for another 
big discussion.  To avoid that, I would suggest to add a number of 
reasons, or whatever to make this assumption sound (more) valid.  It is 
important, I think, that the reader can understand your grounds for 
saying this.
(I personally disagree on this statement now, but it makes no use 
discussing it since you haven't given any ground as on why.  Maybe if 
you would give a definition, I could adjust my own definition and agree.)

> A more reliable way of getting news of critical updates out to users is required
> to avoid repeats of the various recent upgrade debacles.

Perhaps you want to add a small footnote here, to give a small example 
of such debacle, and using that example point out what is the problem 
you think is important, and hence will address in this paper... eh GLEP.

> This GLEP proposes a
> solution based around pushing news items out to the user via the ``rsync`` tree.

This is a minor side issue, but I think that GLEP 2 states that you 
should use ' instead of `.  No discussion on it please, I might be wrong 
or you just didn't know.

> 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"

> No user subscription required
>     It has already been demonstrated [#forums-whining]_ that many users do not
>     read the ``gentoo-announce`` mailing list or ``RSS`` feeds. A solution which
>     requires subscription has no advantage over current methods.

You implicitly state that many users do not read the gentoo-announce 
list and RSS-feeds because they are subscription based.  This sounds 
like a too quick assumption to me.  At least it is not founded in any 
way.  Consider that for RSS-feeds one typically doesn't have to 
subscribe, but just add it to his/her reader.  Make clear why you think 
the subscription model stops users from reading, and why a push-based 
alternative (as you suggest here) will work.  Remember that it is easy 
to say here that users don't read what's on their consoles as well, as 
in post emerge messages etc.  So make sure you deal with it upfront, why 
you think now it *will* work.

> No user monitoring required
>     It has already been demonstrated [#forums-whining]_ that many users do not
>     read news items posted to the Gentoo website, or do not read news items
>     until it is too late. A solution that relies upon active monitoring of a
>     particular source has no advantage over current methods.

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) which 
somehow contradicts previous statements.  Beware that you clearly deal 
with this, or just introduce it earlier so it doesn't look you're 
contradicting yourself.

> 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.

> 3. The news item is committed to a CVS (or Subversion [#glep-36]_) repository.
>    From here, it is merged with the rsync tree. This is described in `News Item
>    Distribution`_.
> 4. The news item is merged with the rsync tree. Implementation details of this
>    point are beyond the scope of this GLEP; existing solutions are in place
>    for merging GLSAs to the tree.

Where does point 4 differ from the second part of point 3?  Also, point 
3 implies that the merging into the rsync tree is being described 
further on, while point 4 states the oposite of not discussing it (out 
of scope).  Maybe split point 3 and merge with 4?

> 5. Users fetch the news item when they sync. This ensures that the news items in
>    question are pushed to the user before the user accidentally makes an
>    unwanted change. No changes to the existing rsync process are required by
>    this GLEP.

I would suggest a reference to a place where you will explain this 
'pushing' to the user in detail.  Especially the time and the way how 
are important.  Or maybe I was just confused by "pushed" and is the only 
thing this point wants to say that all news items are just synced 
together with the rest of the portage tree upon a emerge --sync.  The 
latter sounds logical considering the last sentence quoted above.

> 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.

> 7. The news item is handled by the user's choice of news item reader. See `News
>    Item Clients`_.

Wow.  Seems like point 6 mentioned 'news item reader' too early!  Same 
for point 5 of mentioning "pushing" which is only dealt with in point 6. 
  In any case, the reference is there: good.

> 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.

> An English (``en``) version must be available for all news items. Other
> languages may be provided either by the original author or by other translators
> who have commit access. This anglocentricity is justified on the grounds that
> nobody objected to it with GLEP 34 [#glep-34]_.

This might sound a bit 'attacking'.  Try to rephrase it a bit to sound 
more formal.  Also, note that probably noone cares about it and takes it 
for granted.  You included support for other languages, so there's 
nothing to make a sharp point on here, I guess.
(Maybe: "An English (''en'') version must be available for all news 
items as per GLEP 34 [#glep-34]_.  Other languages ...")

> A news item's content will consist of an RFC 822 [#rfc-822]_ style header
> followed by the main body of the message as plain text. This GLEP defines
> various optional and mandatory headers. Future GLEPs may propose new headers --
> tools handling these news items must ignore any unrecognised header.

Ah, a clear sight on the future.  Good!  (Also from the perspective of 
the paper.)

> ``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?

> ``Posted:``
>     Date of posting, in ``dd-mmm-yyyy`` format (e.g. 14-Aug-2001). UTC time in
>     ``hh-mm-ss +0000`` format may also be included. This field is mandatory.

Consider stressing the requirement for UTC time by stating it in a 
separate sentence.

> ``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.  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.

> The following headers are used for filtering. If none of these headers are
> specified, the news item is displayed for all users. Otherwise, the news item is
> displayed if *at least one* header matches.

 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 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)

>     YourSQL databases created using YourSQL version 4.0 are incompatible
>     with YourSQL version 4.1 or later. There is no reliable way to
>     automate the database format conversion, so action from the system
>     administrator is required before an upgrade can take place.
>
>     Please see the Gentoo YourSQL Upgrade Guide for instructions:
>
>         http://www.gentoo.org/doc/en/yoursql-upgrading.xml

Note that this indenting of the URL can be considered 'fancy 
formatting'.  Hence there is a clear need to define the term.

>
>     Also see the official YourSQL documentation:
>
>         http://dev.yoursql.com/doc/refman/4.1/en/upgrading-from-4-0.html
>
>     After upgrading, you should also recompile any packages which link
>     against YourSQL:
>
>         revdep-rebuild --library=libyoursqlclient.so.12
>
>     The revdep-rebuild tool is provided by app-portage/gentoolkit.

Consider including a new paragraph in the example just to show your 
proposed structure.

> Thus, all proposed news items must be posted to the ``gentoo-dev`` or
> ``gentoo-core`` mailing list, and ``Cc:``\ed to ``pr@g.o`` 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?
In any case:
- 72 hours is a lot (is there a way to shorten it when everything is
   there?)
- consider using either -dev or -core not both in an "OR" relation,
   clarity if good for everyone.
- what if noone feels like commenting on the submission?
- how do you know a certain dev is a competent English speaker?
- when do you know that it has been read, approved?
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.

> 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.  Be aware that there are bugs 
that indicate that users would like to see all einfo messages being 
delivered to them in some way.  It might be confusing to the user what 
is the difference (and for me as well... when is something considered 
important?).  Try to define what you think is important, or maybe give 
some well explanatory examples and what the advantage is over einfo.  To 
comment on your YourSQL example: perhaps YourSQL just gives an error 
about an incompatible database when starting it, and points itself to a 
migration site.  One could consider for this reason a message on it not 
important, as nothing gets unrepairable broken.  Linking back to your 
'preemptive' requirement: define damage and broken.

> The unread news message will also be displayed immediately after an
> ``emerge sync``.

Include a note on configurability, i.e. disabling such behaviour for 
users that don't like it.  Elaborating on other ways to inform the 
administrator (ie. via email) would be great too.  Consider automated 
installs, end-user/desktop installs (basically everything from big to 
small) such that for each situation the information being supplied can 
be pushed to the admin in the way that is desirable (for him/her).

> Portage may also warn of unread news items using, for example, a red flashy
> before actions such as merging a package.
>
> Portage must keep track of news items which have already been installed to avoid
> repeatedly reinstalling a deleted news item.
>
> Users who really don't care about news items can use ``rsync_excludes`` to
> filter out the ``news/`` directory.

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.)

A concluding note on this Section is that I have the impression that 
only one use-scenario has been dealt with.  Both this scenario is not 
described, as well as that this scenario doesn't reflect 99.9% of our 
user base.  Many alternative opinions will stem from the fact that 
different people envision different scenarios.  I think that elaborating 
on a number of representative (need not to be most popular) scenarios 
and how the proposed setup functions in there is good to get a grip on 
the many different demands of users.  I could help to define a scenario 
for a larger scale more or less automated/cronned install.

> News Item Clients
> -----------------
>
> Once a news item is 'installed', third party tools (or a traditional Unix pager
> and ``rm``) can be used to display and view the news files. An ``eselect``
> [#eselect]_ module shall be created as the 'suggested' display tool; other
> display tools (for example, a news to email forwarder, which would be ideal for
> users who sync on a cron) are left as options for those who desire them -- the
> simple file format make this relatively simple.

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.

> News Item Removal
> -----------------
>
> News items can be removed (by removing the news file from the main tree) when
> they are no longer relevant, if they are made obsolete by a future news item or
> after a long period of time. This is the same as the method used for ``updates``
> entries.

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.

> Integration with Existing Systems
> =================================
>
> It would be trivial to convert these news items into the format used for news
> items on the Gentoo website or posts for the ``gentoo-announce`` mailing list.

Yes, and make it a requirement that all news messages get posted 
somewhere on public channels.  Some admins really like to see all news 
items, so your GLEP should cover the possibility for that, I think.
Somewhat related to my suggestion for using scenarios, this also implies 
that there will be users that want to turn this off completely, as such 
doing the right rsync_exclude should be documented somewhere.



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.  Given the fact I had a lot to add, indicates for me there are a 
lot of questions to be asked regarding this GLEP.  Many of those 
questions can simply be answered by providing the underlying rationales 
and background information that is not made explicit.  I hope you can do 
something useful with my comments.  If you don't like them, ignore them 
and throw them away.  If you want to use them, feel free to do so.


-- 
Fabian Groffen
Gentoo for Mac OS X Project -- Interim Lead
-- 
gentoo-dev@g.o mailing list