The attached GLEP is a draft proposal for the emerge --news thing that's been under discussion. There are still some TODO items. These are calls for people to weigh in with suggestions. Of course, suggestions on other items are good too...
There is currently no explanation as to why this GLEP should be chosen over ChrisWhite's 42. I will add such a section if anyone requests it. Grant, please pick me a number. I'll post this one to -user and the forums if it survives a round or two of being shot at in here first... -- Ciaran McCreesh : Gentoo Developer (Vim, Shell tools, Fluxbox, Cron) Mail : ciaranm at gentoo.org Web : http://dev.gentoo.org/~ciaranm
GLEP: XX
Title: Critical News Reporting
Version: $Revision: $
Author: Ciaran McCreesh <[EMAIL PROTECTED]>
Last-Modified: $Date: $
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 31-October-2005
Post-Date: 1-November-2005
Abstract
========
This GLEP proposes a new way of informing users of important updates and
news regarding tree-related items.
Motivation
==========
There are currently several ways of getting news out to our users, none of
them particularly effective:
* Gentoo Weekly News
* The ``gentoo-announce`` mailing list
* The Gentoo Forums
* The main Gentoo website
A more reliable way of getting news of critical updates out to users is
required to avoid repeats of the various recent upgrade debacles.
Requirements
============
An adequate solution must meet all of the following requirements:
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. In particular, this means that any markup to be parsed must be
in a very simple format.
Relevant
System administrators who do not use a particular package should not
have to read news items which affect purely that package. Some news
items may be of relevance to most or all users, but those that are
not should not be forced upon users unnecessarily.
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.
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.
No privacy violations
Users of the solution should not be required to provide information
about their systems (for example, IP addresses or installed packages).
Preemptive
Users should be told of changes *before* they break the user's system,
not after the damage has already been done.
The following characteristics would be desirable:
Internationalisable
Being able to provide messages in multiple languages may be
beneficial.
Quality control
There should be some way to ensure that badly written or irrelevant
messages are not sent out, for example by inexperienced developers,
those whose English language skills are below par or morons.
Simple for developers
Posting news items should be as simple as is reasonably possible.
Simple for users
Reading relevant news items should be as simple as is reasonably
possible.
Compatibility with existing news sources
It would be ideal if a news system could easily be integrated with the
existing communication methods.
Specification
=============
The following specification is based upon Stuart's "Favouring an automatic
news mechanism" post [#stuart-blog]_ and discussion on the ``gentoo-dev``
mailing lists [#dev-thread]_ and the ``#gentoo-dev`` IRC channel.
News Item Source
----------------
News items are to be made available via the Portage tree. This removes any
need for polling of a remote source.
A new directory, ``news/``, will be created in the main tree. Commit access
to this directory will be handled in the same way as for the rest of the
tree. This directory will contain further subdirectories named
``yyyy-mm/``, where ``yyyy`` is the current year and ``mm`` is the current
month number (01 for January through 12 for December) -- this extra level
of separation will help keep news items more manageable.
Users who really don't care about news items can use ``rsync_excludes`` to
filter out the ``news/`` directory.
.. Note:: The ``profiles/`` directory will *not* be used. This fits in with
the Portage team's future plans for ``profiles/`` and ``metadata/``
separation.
Each news item will be represented by a single text file. This file will
be encoded using UTF-8 for compatibility with and for the same reason as
existing Gentoo documentation [#docs-policy]_ and tree [#glep-31]_ practices.
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 directory and file name rules are designed specifically to allow easy
sorting by date.
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]_.
News Item File Format
---------------------
A news item 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 discard any unrecognised header.
News Item Metadata Headers
''''''''''''''''''''''''''
``Title:``
A short (maximum 44 characters) descriptive title. Mandatory.
``Author:``
Author's name and email address, in the form
``Real Name <[EMAIL PROTECTED]>``. Mandatory, multiple author fields may
be specified if appropriate.
``Translator:``
For translated news items, the translator's name and email address.
``Content-Type:``
Must be ``text/plain``. Mandatory.
``Posted:``
Date of posting, in ``dd-mmm-yyyy`` format (e.g. 14-Aug-2001).
Mandatory.
``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.
News Item Relevance Headers
'''''''''''''''''''''''''''
If none of the following headers are specified, the news item is aimed at
all users. Otherwise, the news item should only be displayed if at least
one of the criteria matches.
``Display-If-Installed:``
A dependency atom or simple package name (for example,
``<dev-lang/php-5_alpha`` or ``net-www/apache``). If the user has the
package specified installed, the news item should be displayed.
``Display-If-Keyword:``
A keyword [#glep-22]_ name, for example ``mips``. If the user is on
the arch in question, the news item should be displayed.
TODO: Display-If-USE for USE flag renames?
TODO: Display-If-Mode: ``any`` or ``all`` or ``none`` with ``any`` being
the default?
News Item Body
''''''''''''''
The header section must be followed by a blank line, then the main body of
the text.
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.
Example News Item
'''''''''''''''''
The following hypothetical news item would be placed in
``news/2005-11/2005-11-01-mysql-4.0-4.1-upgrade.en.txt``.
::
Title: YourSQL Upgrades from 4.0 to 4.1
Author: Ciaran McCreesh <[EMAIL PROTECTED]>
Content-Type: text/plain
Posted: 01-Nov-2005
Display-If-Installed: <dev-db/yoursql-4.1_alpha
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
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.
.. Note:: The presence of URLs in a news item does not contradict the "no
need for a web browser" requirement. Many systems are administered
remotely, for example over ``ssh``.
News Item Quality Control
-------------------------
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.
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.
There have been complaints regarding the comprehensibility of some upgrade
notices and news items in the past. This is understandable -- not every
Gentoo developer speaks English as a first language. However, for the sake
of clarity and professionalism it is important that any language problems
be corrected before inflicting a news item upon end users.
News Item Display
-----------------
Whenever relevant unread news items are found, ``emerge`` will copy the
news file into ``/var/lib/gentoo/news/``.
TODO: or ``/var/gentoo/news/`` or ``/etc/gentoo/news/``? And make it
overridable by an environment variable?
Notification that new relevant news items will be displayed via the
``emerge`` tool in a similar way to the existing "configuration files need
updating" messages:
::
* Important: 3 config files in /etc need updating.
* Type emerge --help config to learn how to update config files.
* Important: there are 5 unread news items.
* Type emerge --help news to learn how to read news files.
From there, third party tools (or a traditional Unix pager and ``rm``) can
be used to display and view the news files. An ``eselect`` [#eselect]_
module can easily be created as the 'suggested' display tool; other
display tools (for example, a news to email forwarder) are left as options
for those who desire them -- the simple file format make this relatively
simple.
TODO: Implementation detail: what's the easiest way to keep track of
"stuff that has already been copied over" to avoid duplicating news? A
straight list with filtered language codes in a text file is the obvious
solution...
News Item Removal
-----------------
News items can be removed (by removing the news file from the main tree)
when they are no longer relevant, or after a long period of time. This is
the same as the method used for ``updates`` entries.
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.
There is an existing automated tool for posting GLSAs to the forums. A
similar tool can be used for these news items.
TODO: reference for the above. or did I just make it it?
Backwards Compatibility
=======================
Backwards compatibility is not a concern here. Existing tools will simply
ignore the ``news/`` directory.
Reference Implementation
========================
TODO
References
==========
.. [#dev-thread] "[gentoo-dev] Getting Important Updates To Users",
http://marc.theaimsgroup.com/?t=113065837900001&r=1&w=2
.. [#docs-policy] Gentoo XML Guide, Daniel Robbins et al.,
http://www.gentoo.org/doc/en/xml-guide.xml
.. [#eselect] eselect modular framework for configuration and
administration utilities,
http://www.gentoo.org/proj/en/eselect/index.xml
.. [#forums-whining] Gentoo Forums thread "Gentoo Apache2 Config Change
Idiocy",
http://forums.gentoo.org/viewtopic-t-384368.html
.. [#glep-22] GLEP 22: "New "keyword" system to incorporate various
userlands/kernels/archs", Grant Goodyear,
http://www.gentoo.org/proj/en/glep/glep-0022.html
.. [#glep-31] GLEP 31: "Character Sets for Portage Tree Items", Ciaran
McCreesh,
http://www.gentoo.org/proj/en/glep/glep-0031.html
.. [#glep-34] GLEP 34: "Per-Category metadata.xml Files", Ciaran McCreesh,
http://www.gentoo.org/proj/en/glep/glep-0034.html
.. [#iso-639] ISO 639 "Code for the representation of names of languages"
.. [#rfc-822] RFC 822 "Standard for the format of ARPA Internet text
messages"
.. [#stuart-blog] "Favouring an automatic news mechanism", Stuart Herbert,
http://stu.gnqs.org/diary/gentoo.php/2005/10/28/favouring_an_automatic_news_mechanism
Credits
=======
Thanks to Brian Harring, Stuart Herbert, Donnie Berkholz, Alec Warner and
Dan Meltzer for input. Some of the ideas presented here are theirs, others
go completely against their suggestions.
Copyright
=========
This document has been placed in the public domain.
.. vim: set tw=74 fileencoding=utf-8 spell spelllang=en :
pgpEfbDnDUKCz.pgp
Description: PGP signature
