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

[Brian Harring]

On Sat, Nov 05, 2005 at 12:58:14AM +0000, Ciaran McCreesh wrote:
> 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.
>
<snip>

> 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 trivial to write clients for displaying
>     news items in different ways.

Drop the lightweight bit and merge it into multiple delivery.  You're 
after lightweight _default_, which is fine, but the phrasing is a bit 
screwed.

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

While it may be fun getting a reaction out of people, nuke the nitro 
laced words please.  Same for the forums_whining ref (there's enough 
contention over the glep already ;)


> News items are published and delivered to users as follows:
<snip>
> 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.

Out of curiousity, how are you planning on having 101 general notices 
reigned down on a users head during an initial install?  Yes, you have 
the atom filter, but what about general notices?

Further, how are notices going to apply to users who don't have the 
package installed, then go and merge it?  Your statement above implies 
the irrevalent (at the time of sync) notices are ignored, which breaks 
down under the scenario where a news item is pushed out that apache 
configuration is going to change, I merge old style apache after 
sync'ing the news, portage (due to your news id cache) considers it 
deleted, and doesn't display it.


> News Item File Format
> ---------------------
<snip>
> News items may be signed using GPG. If this is done, a detached signature should
> be used.

I'd argue for must be, personally.  A bogus news item claiming to be 
from portage devs, telling users to change their SYNC setting could 
cause massive mayhem.


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

Still haven't address my point about
A) package moves combined with news entries
B) N packages

Assume you mean that the bit above is a full DepSet, not a single atom 
(if that's the case, clarify that N atoms are allowed).

Should clarify USE conditionals are a no go- might be worth 
considering the full atom syntax (despite the fact portage doesn't 
currently support it for depends), use flags, slot, etc.

Yes it's more work, but it should be spelled out from where I'm 
sitting.

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

N keywords == N Header entries?

> 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.
>
> Thus, all proposed news items must be posted to the ``gentoo-dev`` or
> ``gentoo-core`` mailing list

No go on -core imo; it's a community/dev issue, should be visible to 
the general public rather then hidden away in the ml we do our flaming 
in.

> Client Side
> '''''''''''
>
> Whenever relevant unread news items are found, ``emerge`` will copy or symlink
> the news file into ``/var/lib/gentoo/news/``.

Already pointed out that this won't fly looking forward, it implicitly 
assumes a single repository.

Need to allow for each repo to have their own news, preferably 
seperated directory wise; either that or you're going to have to track 
where a news item came from and mangle the new entry.

> 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.
>
> The unread news message will also be displayed immediately after an
> ``emerge sync``.
>
> Portage may also warn of unread news items using, for example, a red flashy
> before actions such as merging a package.

Nuke flashy (any phrasing that allows for blinking crap sliding into portage I 
instinctively dislike).

> Portage must keep track of news items which have already been installed to avoid
> repeatedly reinstalling a deleted news item.

Track it how, via the directory, or a secondary list?
Wording implies portage is going to have to maintain it's own newsid 
list; if that's the case, explicitly state so, and keep it limited to 
per repo (not global as the proposal seems to indicate).

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

Might want to consider a maximum period of time for news entries to 
linger by default; perhaps a header for controlling deletion (this is 
would require commit access for whatever does the scans obviously).

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

Stop using trivial (no it's not in reference to above, just hit the 
right word count where I'm whinging about it).


> Reference Implementation
> ========================
>
> Portage Code
> ------------
>
> TODO

Points above regarding working sanely for N repos need be addressed, 
plus any implementation needs to be integrated, not handing off to an 
external tool (don't want 2 different implementations of atom 
parsing).

Personally... I still think package level news should not be treated 
as repository level information.  It makes any attempt at glep19 a bit 
trickier and stores package data in two different locations.
So... reiterating jasons question, example where news items transcend 
package specific?
~harring