Re: [gentoo-dev] GLEP 42 (News) revisited

[Alec Warner]

Stephen Bennett wrote:
> Since GLEP 42's original author and sponsor has left the project, I've
> taken it over, and would like to have another go at getting it
> implemented. I've just updated the version in CVS[1], which should be
> making its way onto the www nodes, but with any luck the full text
> should be attached here for convenience.
>
> So, I'd like to ask for any further input on this, and if noone has any
> major issues with it, I'd like to put it into the Council's queue for
> discussion at the next opportunity.
>
> Changes since the previous posted version:
>
>  * Added details of a reference implementation.
>
>
> ------------------------------------------------------------------------
>
> GLEP: 42
> Title: Critical News Reporting
> Version: $Revision: 1.10 $
> Author: Ciaran McCreesh <ciaranm@g.o>
> Last-Modified: $Date: 2006/06/12 22:03:07 $
> Status: Draft
> Type: Standards Track
> Content-Type: text/x-rst
> Created: 31-Oct-2005
> Post-History: 1-Nov-2005, 5-Nov-2005, 7-Nov-2005, 11-Dec-2005, 13-Dec-2005, 18-Dec-2005, 5-Jan-2006, 2-Mar-2006, 6-Mar-2006, 12-Jun-2006
>
> Abstract
> ========
>
> This GLEP proposes a new way of informing users about important updates and news
> related to the tree.
>
> Motivation
> ==========
>
> Although most package updates are clean and require little user action,
> occasionally an upgrade requires user intervention.  Recent examples of the
> latter include the ``gcc-3.4`` stabilisation on ``x86`` and the ``mysql-4.1``
> database format changes.
>
> There are currently several ways of delivering important news items to our
> users, none of them particularly effective:
>
> * Gentoo Weekly News
> * The ``gentoo-announce``, ``gentoo-user`` and ``gentoo-dev`` mailing lists
> * The Gentoo Forums
> * The main Gentoo website
> * RSS feeds of Gentoo news
> * ``einfo`` and ``ewarn`` messages in ``pkg_setup`` or ``pkg_postinst``
>
> A more reliable way of getting news of critical updates out to users is required
> to avoid repeats of various prior upgrade debacles. This GLEP proposes a
> solution based around pushing news items out to the user via the ``rsync`` tree.
>
> .. Important:: This GLEP does not seek to replace or modify ``einfo`` messages
>    which are displayed post-install. That is a separate issue which is handled
>    by ``elog`` [#bug-11359]_.
>
> Requirements
> ============
>
> An adequate solution must meet all of the following requirements:
>
> Preemptive
>     Users should be told of changes *before* they break a system, not after the
>     damage has already been done. Ideally, the system administrator would be
>     given ample warning to plan difficult upgrades and changes, rather than only
>     being told just before action is necessary.
>
> No user subscription required
>     It has already been demonstrated [#forums-apache2]_ that many users do not
>     read the ``gentoo-announce`` mailing list or ``RSS`` feeds. A solution that
>     requires subscription has no advantage over current methods.
>
> No user monitoring required
>     It has already been demonstrated [#forums-apache2]_ 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.
>
> 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.
>
> 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.
>     Users must not be forced to install unreasonable extra software to be able
>     to read news items.
>
> No privacy violations
>     Users of the solution should not be required to provide information about
>     their systems (for example, IP addresses or installed packages).
>
> Multiple delivery method support
>     Some users may wish to view news items via email, some via a terminal and
>     some via a web browser. A solution should either support all of these
>     methods or (better still) make it simple to write clients for displaying
>     news items in different ways.
>
> 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 or those whose
>     English language skills are below par.
>
> 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 and future news sources
>     A news system would ideally be able to be integrated with existing news
>     sources (for example, Forums, GWN, the main Gentoo website) without
>     excessive difficulty. Similarly, easy interoperation with any future news
>     sources should not be precluded.
>
> Specification
> =============
>
> Overview
> --------
>
> News items are published and delivered to users as follows:
>
> 1. A news item is written. The format to be used is described below.
>
> 2. The news item is reviewed, following the process described in
>    `News Item Quality Control`_.
>
> 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. 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.
>
> 5. The package manager filters the news item and, if it is relevant, marks the
>    news item for reading. The package manager should also display a notice
>    informing the user that there are unread news items.
>
> 6. The news item is handled by the user's choice of news item reader. See `News
>    Item Clients`_.
>
> Required Portage Enhancements
> -----------------------------
>
> The following extensions to Portage are required:
>
> * Every repository (including overlays) will require a unique identifier. It is
>   assumed that an identifier will be a string consisting of characters from
>   ``a`` to ``z``, ``A`` to ``Z``, ``0`` to ``9``, ``+`` (plus), ``-`` (hyphen)
>   ``_`` (underscore).
>
done

> * Portage must provide a way for external programs to obtain a list of all
>   repository identifiers for a given system. It is assumed that this will be in
>   the form of a ``portageq`` command (e.g. ``portageq get_repo_ids``).
>

not done, and if we implemented it, would be a hack (although 
compromisable in this scheme, would be essentially a fake portageq command)

> * Portage must provide a way for external programs to obtain the base path for
>   a repository with a given ID. It is assumed that this will be in the form of
>   a ``portageq`` command (e.g. ``portageq get_repo_root gentoo-x86``).

same as above

>
> * Portage must extend ``portageq has_version`` to support restrictions to a
>   given repository ID.

and again

>
> * Portage must extend ``portageq`` to implement a command which returns whether
>   or not the profile used for a given repository ID is exactly the given profile
>   (e.g. ``portageq profile_used default-linux/sparc/sparc64/2004.3
>   gentoo-x86``).

and again

>
> These extensions are assumed during the following specification.
>

I have no problem with basically writing up 'fake' portageq calls. 
However often people tell me overlays are important, they don't serve as 
multipile repos and don't have metadata/news, so they are excluded in 
this specification (intentially?).  Portage doesn't do multiple repo's 
so any repo-related call will be a 'fake' one, that just returns the 
expected data, unless someone has a better method (looks at other 
portage devs).

>
> News Item Quality Control
> -------------------------
>
> 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,
> professionalism and avoiding making us look like prats, it is important that any
> language problems be corrected before inflicting a news item upon end users.
>
> Thus, at least 72 hours before a proposed news item is committed, it must be
> posted to the ``gentoo-dev`` mailing list and ``Cc:``\ed to ``pr@g.o``
> (exceptions may be made in exceptional circumstances). Any complaints — for
> example regarding wording, clarity or accuracy — **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. The importance of the message to its
> intended audience should be justified with the proposal.
>
> .. Important:: The filtering system means that it is appropriate to send out
>    news items which are aimed at users of an uncommon package or architecture.
>    Thus, the justification should be in the form "this message is important to
>    YourSQL users because ...", not "YourSQL is important because ...".
>

I am not sure if I pointed this out before, but I feel that news items 
should be of a pragmatic nature.  IE they should be useful but not 
frequent.  It should not be overly difficult to post a news item for a 
particular incident.  If news items are constantly being shot down due 
to "importance" or some other reason that lacks what I would call a 
reasonable blocking reason ( ie bad grammar, clarity problems, 
inaccuracies ) it will discourage developers from submitting them. 
While I am against completely crap news items, I would rather see more 
news items than very few.

>
> Integration with Existing Systems
> =================================
>
> It would be simple 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 [#forums-glsa]_ for posting GLSAs to the
> forums. A similar tool can be used for these news items.
>

I would prefer to hear arguments about whether news items should be 
posted to announce or to a seperate ML.  I would also like to see 
integration via a "news" link on p.g.o.  I would be willing to assist in 
the latter.
-- 
gentoo-dev@g.o mailing list