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
PROTECTED]>``.
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 [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?
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@gentoo.org mailing list
