[gentoo-dev] GLEP 42 (Was: Getting Important Updates To Users)

[gentoo-dev] GLEP 42 (Was: Getting Important Updates To Users)

[Chris White]

[-- Attachment #1.1: Type: text/plain, Size: 172 bytes --]

Attached in plain text form is glep 42 for the discussed thread.

It's rather long, but I hope it details any sort of questions that may be 
brought up.

Chris White

[-- Attachment #1.2: glep-0042.txt --]
[-- Type: text/plain, Size: 7061 bytes --]

GLEP: 42
Title: Centralized User Updates
Version: $
Last-Modified: $
Author:	Chris White <chriswhite@gentoo.org>
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 31-October-2005
Post-History: 31-October-2005


Credits
=======

Ideas presented here are a collection of those presented in the gentoo-dev
mailing list, and were headstarted by a planet blog entry by Stuart.

Abstract
========

This GLEP covers the current state of providing users with a centralized source
of news acquisition.  The centralized areas of information will propigate from a
single source and be distributed through multiple points of user outreach.

Motivation
==========

Motivation for the creation of this GLEP lies within the present state of afairs
in providing mission critical update notices to our (Gentoo) user base.
Currently, there are several de-centralized mediums of providing information.
These include:

	1. The GWN
	2. The Gentoo forums
	3. The Gentoo Developer mailing list
	4. Other assorted mailing lists

In the current state of affairs, the previously mentioned mediums have the
distinct issue of being seldomly inter-linked.  This means that if a user does
not take part in a certain medium used for distributing important notices, they
will be unable to take action on the information.  This could mean the swift
difference between a working and unusable system.  Examples of this
include:

	1. Major kernel upgrades
	2. Server updates
	3. Major server extension updates
	4. Base system layout updates (expecially in the area of networking)

Real world examples of this already exist in the Kernel 2.4 to 2.6 updates,
Apache layout changes, PHP restructuring, and networking support updates.  While
these stated examples could have performed reasonably well, they could of done
better, leading into the implementation of this GLEP.

Implementation
==============

First off, it's best one start with the main centralized medium of information,
the gentoo.org front page.

Front Page
----------

When a new user first is introduced to Gentoo, they are frequently redirected to
the gentoo.org front page.  Here is where users first get a glimpse of what
Gentoo is, how it works, and most importantly, where to recieve information on
updates.  If a user notices a large number of upgrade and maintainance reports
on the gentoo.org front page, they are more likely to return to it as their
source of information.  With the current system, users have no solid centralized
form of information.  They are told that we (Gentoo) have support avaliable from
our forums, mailing lists, irc channel, and GWN.  However, it does not tell them
where critical updates can be found.  This is why the front page should have
news updates on critical information.  However, while users may see the page and
know the news is there, they might not have the time to actively monitor it.
This leads to the next form of interaction: RSS feeds.

RSS Feeds
---------

Currently, the main front page provides an RSS feed for users.  This would
benifit users who want updates propigated to them in a non-interactive manner.
One would come back and find new updates automatically provided to them through
their rss aggregator of choice.  Now users are more likely to obtain their news,
as it is a rather non-obtrusive method of information.  While the RSS feed is
definately a non-obtrusive way to reach users, another more widely read medium
is also avaliable, the forums.

Gentoo Forums
-------------

The forums happen to be one of the largest support forums on the web.  That
said, they are widely read by Gentoo users for troubleshooting and other forms
of information.  The front page news should most definately be accessed through
the forums as well.  This ensures a large audience to updates.  A News & 
Announcements forum already exists for this purpose, and can be utilized
accordingly. However, some people may already be signed up on various mailing 
lists, and want information provided there instead.  One such list is 
gentoo-announce.  

gentoo-announce mailing list
----------------------------

The gentoo-announce mailing list's main function is to provide important
announcements to users.  These important announcements can be considered the
same as those that should be displayed on the main page.  That said, the main
page news feeds should also be sent to gentoo-announce.  This can either be done
through script automation or manual posting.  However, there is also an inherit
problem of users that don't use the internet that frequently, or an rss
aggregator is not a suitable option for them.  This leads to the next form of
implementation: Portage.

emerge --news support
---------------------

As already mentioned by Stuart, in this way users are bound to the one thing
guaranteed on their system: Portage.  Through portage, the same location where
etc-update notifications are displayed (after emerge --sync and at the finish of
an emerge), will contain a notice about news updates.  These news updates should
come in the form of a file contained within the portage tree for users that want
news updates on a networkless system. Should the user run these items in the
background or send the output to /dev/null for any reason, a --news option
should also be avaliable in emerge for them to review the news at a convient
time.

Example of Implementation
=========================

This is a sample of the implmentation, but can be modified if needed:

	1) A directory is someplace called "updates" or close to it
	2) A capable person posts a bug report/sends out for peer review on a
	news posting
	3) If the news is accepted, it is posted to the front page
	4) The front page code will do the following
		a) Insert the information into the site database
		b) Send an email out with the information with a specific
		template
		c) Cross-insert into the forums (possible?)
		d) Append text to a plain text file for users to sync with
		portage.  This will be created on demand with the other actions,
		or applied with a cron job of some sort.

Rationale
=========

The implementation of this is an benefit to both users and developers alike.
Users benefit in the ability to access information in a centralized location.
Developers benefit in a better assurance that critical updates get through to
users, and less bugs evolving from those updates.  In addition, most of the
mediums of information already exist, so the ammount of new work to be done is
minimized (ie. the front page can already have postings made to it, the
gentoo-announce mailing list already exists, forums already exist).  The only
thing that is still questionable is the implementation in Portage.

Backwards Compatibility
=======================

With the possible exception of Portage, nothing is required to be backported.

Copyright
=========

This document has been placed in the public domain.

[-- Attachment #2: Type: application/pgp-signature, Size: 190 bytes --]

[gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Dan Meltzer]

s/where headstarted by a blog post by Stuart/where headstarted by bug 11359/

To jump right in :)

On 10/31/05, Chris White <chriswhite@gentoo.org> wrote:
> Attached in plain text form is glep 42 for the discussed thread.
>
> It's rather long, but I hope it details any sort of questions that may be
> brought up.
>
> Chris White
>
>

-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] GLEP 42 (Was: Getting Important Updates To Users)

[Brian Harring]

[-- Attachment #1: Type: text/plain, Size: 1166 bytes --]

On Tue, Nov 01, 2005 at 08:36:23AM +0900, Chris White wrote:
> Attached in plain text form is glep 42 for the discussed thread.
> emerge --news support
> ---------------------
> 
> As already mentioned by Stuart, in this way users are bound to the one thing
> guaranteed on their system: Portage.  Through portage, the same location where
> etc-update notifications are displayed (after emerge --sync and at the finish of
> an emerge), will contain a notice about news updates.  These news updates should
> come in the form of a file contained within the portage tree for users that want
> news updates on a networkless system. Should the user run these items in the
> background or send the output to /dev/null for any reason, a --news option
> should also be avaliable in emerge for them to review the news at a convient
> time.

And this file is what format?  How is the format going to be 
structured so that emerge can know what entries to ignore?  How is 
emerge going to pull those entries again?

What restrictions are there for what goes into this file, to keep the 
signal to noise ratio sane?
Etc.

Details man, details.
~harring

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

[gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Dan Meltzer]

Bah, replied to fast.

Other points of note...

1) Why post to forums.g.o if its on www, why would one check forums
instead of www.

2) Theoretically it could be crossposted to the forums, probably
simplest to do as a direct mysql insert, which'd be messy.

3) --news, my point of reamage.

This is what   bug 11359 was all about, I'm not quite sure why the
wheel has been brought up for reinvention, this is most likely going
to be a large change, and it seems that, instead of bugging portage
developers to add more stuff to 2.0 series, which is basically
relegated to bugfixes, we should just let them hack away at savior,
which will have this support integrated (hell, it has it already). 
Having a temporary hack is pointless IMNSHO.

In addition, seems like this could simply be something like
glsa-check, call it news-update why don't we, which simply reads from
the RSS feed (oh wow, i'm a genius!).  Make this part of system, 
convince the baselayout guys (this is a lot easier even) to make
emerge an alias that calls $(news-update) after emerge, and whaddya
know, we have liftoff!

On 10/31/05, Dan Meltzer <parallelgrapefruit@gmail.com> wrote:
> s/where headstarted by a blog post by Stuart/where headstarted by bug 11359/
>
> To jump right in :)
>
> On 10/31/05, Chris White <chriswhite@gentoo.org> wrote:
> > Attached in plain text form is glep 42 for the discussed thread.
> >
> > It's rather long, but I hope it details any sort of questions that may be
> > brought up.
> >
> > Chris White
> >
> >
>

-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] GLEP 42 (Was: Getting Important Updates To Users)

[Ciaran McCreesh]

[-- Attachment #1: Type: text/plain, Size: 422 bytes --]

On Tue, 1 Nov 2005 08:36:23 +0900 Chris White <chriswhite@gentoo.org>
wrote:
| Attached in plain text form is glep 42 for the discussed thread.

This isn't a GLEP. It's a list of vague ideas that doesn't propose
anything concrete or discussable.

-- 
Ciaran McCreesh : Gentoo Developer (Vim, Shell tools, Fluxbox, Cron)
Mail            : ciaranm at gentoo.org
Web             : http://dev.gentoo.org/~ciaranm


[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Wernfried Haas]

On Mon, Oct 31, 2005 at 06:52:04PM -0500, Dan Meltzer wrote:
> 1) Why post to forums.g.o if its on www, why would one check forums
> instead of www.
Redundancy - to get the attention of those folks that for whatever
reason visit the forums and not www.gentoo.org in a specific time
interval. The more places you cover, the more likely people will see it
somewhere. We've been doing that with GLSAs for quite a while now.

cheers,
	Wernfried

-- 
Wernfried Haas (amne) - amne at gentoo dot org
Gentoo Forums: http://forums.gentoo.org
IRC: #gentoo-forums on freenode - email: forum-mods at gentoo dot org
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] GLEP 42 (Was: Getting Important Updates To Users)

[Jason Stubbs]

On Tuesday 01 November 2005 08:46, Brian Harring wrote:
> On Tue, Nov 01, 2005 at 08:36:23AM +0900, Chris White wrote:
> > Attached in plain text form is glep 42 for the discussed thread.
> > emerge --news support
> > ---------------------
> >
> > As already mentioned by Stuart, in this way users are bound to the one
> > thing guaranteed on their system: Portage.  Through portage, the same
> > location where etc-update notifications are displayed (after emerge
> > --sync and at the finish of an emerge), will contain a notice about news
> > updates.  These news updates should come in the form of a file contained
> > within the portage tree for users that want news updates on a networkless
> > system. Should the user run these items in the background or send the
> > output to /dev/null for any reason, a --news option should also be
> > avaliable in emerge for them to review the news at a convient time.
>
> And this file is what format?  How is the format going to be
> structured so that emerge can know what entries to ignore?  How is
> emerge going to pull those entries again?
>
> What restrictions are there for what goes into this file, to keep the
> signal to noise ratio sane?
> Etc.
>
> Details man, details.

But before details, what is the reasoning in turning emerge into an offline 
news reader? So that admins that don't care enough to source news information 
via other supported means are covered? What's the functional difference 
between this "emerge --news" and the existing "emerge --changelog"? I'd like 
bugs to be better described; should a tutorial be added to emerge as well?

--
Jason Stubbs
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Chris Gianelloni]

[-- Attachment #1: Type: text/plain, Size: 1384 bytes --]

On Tue, 2005-11-01 at 08:56 +0100, Wernfried Haas wrote:
> On Mon, Oct 31, 2005 at 06:52:04PM -0500, Dan Meltzer wrote:
> > 1) Why post to forums.g.o if its on www, why would one check forums
> > instead of www.
> Redundancy - to get the attention of those folks that for whatever
> reason visit the forums and not www.gentoo.org in a specific time
> interval. The more places you cover, the more likely people will see it
> somewhere. We've been doing that with GLSAs for quite a while now.

Exactly.

While I agree that we need a single source where users can get their
information, I feel that the *user* should be able to choose their
source.  If that is the gentoo-announce mailing list, or www.gentoo.org,
or the forums, it doesn't matter.  The same information should be
duplicated.

Make them *all* a definitive source.  We don't need to check all of them
if any one of them gives all of the information needed.

As for subscriber counts or whatever, if by adding the information to
gentoo-announce (or the forums or wherever), we reach 10 more users that
we wouldn't have reached before, then I consider it a success.  The idea
is to reach as many users as possible here.  To me, that means
duplicating the information everywhere.

-- 
Chris Gianelloni
Release Engineering - Strategic Lead
x86 Architecture Team
Games - Developer
Gentoo Linux

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Stuart Herbert]

[-- Attachment #1: Type: text/plain, Size: 1138 bytes --]

On Tue, 2005-11-01 at 08:56 +0100, Wernfried Haas wrote:
> On Mon, Oct 31, 2005 at 06:52:04PM -0500, Dan Meltzer wrote:
> > 1) Why post to forums.g.o if its on www, why would one check forums
> > instead of www.
> Redundancy - to get the attention of those folks that for whatever
> reason visit the forums and not www.gentoo.org in a specific time
> interval. The more places you cover, the more likely people will see it
> somewhere. We've been doing that with GLSAs for quite a while now.

The users I've spoken to about our news situation have expressly stated
that one of their concerns is that there are *too many* places to check
for news.

They're not looking for us to scatter news across many mediums - they
want one place to go.

Best regards,
Stu
-- 
Stuart Herbert                                         stuart@gentoo.org
Gentoo Developer                                  http://www.gentoo.org/
                                              http://stu.gnqs.org/diary/

GnuGP key id# F9AFC57C available from http://pgp.mit.edu
Key fingerprint = 31FB 50D4 1F88 E227 F319  C549 0C2F 80BA F9AF C57C
--

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Chris Gianelloni]

[-- Attachment #1: Type: text/plain, Size: 1621 bytes --]

On Tue, 2005-11-01 at 19:32 +0000, Stuart Herbert wrote:
> On Tue, 2005-11-01 at 08:56 +0100, Wernfried Haas wrote:
> > On Mon, Oct 31, 2005 at 06:52:04PM -0500, Dan Meltzer wrote:
> > > 1) Why post to forums.g.o if its on www, why would one check forums
> > > instead of www.
> > Redundancy - to get the attention of those folks that for whatever
> > reason visit the forums and not www.gentoo.org in a specific time
> > interval. The more places you cover, the more likely people will see it
> > somewhere. We've been doing that with GLSAs for quite a while now.
> 
> The users I've spoken to about our news situation have expressly stated
> that one of their concerns is that there are *too many* places to check
> for news.

Did you specifically ask them if it is because we have different news in
different locations?  Somehow I think you're obscuring some facts to
make your own argument.

Allow me to make this one.  If I want to get all of my facts from
gentoo-announce, do I give a damn if the same thing is *also* posted on
www.gentoo.org for others to read?  Does it somehow inhibit my ability
to get all of the news from gentoo-announce?

> They're not looking for us to scatter news across many mediums - they
> want one place to go.

The only problem that we have now with our multiple mediums is that not
all news is on all mediums.  We should have the same information going
to all of these and let the user choose which method they like for
getting news.

-- 
Chris Gianelloni
Release Engineering - Strategic Lead
x86 Architecture Team
Games - Developer
Gentoo Linux

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Mike Williams]

On Tuesday 01 November 2005 19:32, Stuart Herbert wrote:
> > > 1) Why post to forums.g.o if its on www, why would one check forums
> > > instead of www.
> > Redundancy - to get the attention of those folks that for whatever
> The users I've spoken to about our news situation have expressly stated
> that one of their concerns is that there are *too many* places to check
> for news.
>
> They're not looking for us to scatter news across many mediums - they
> want one place to go.

This user would prefer important news in as many places as possible.
Yes, scattering different types of news about the tree in different places is 
stupid, having the same news in 4 different places might be mildly annoying 
if you see it 4 times, but if 4 times as many users see it all the better.
Redundancy is a Good Thing.

-- 
Mike Williams
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Stuart Herbert]

[-- Attachment #1: Type: text/plain, Size: 2128 bytes --]

On Tue, 2005-11-01 at 14:51 -0500, Chris Gianelloni wrote:
> Did you specifically ask them if it is because we have different news in
> different locations?  Somehow I think you're obscuring some facts to
> make your own argument.

That seems an unpleasant accusation to make :(

The answer is that I didn't ask them if it was because we have different
news in different locations.  The question didn't occur to me.

> The only problem that we have now with our multiple mediums is that not
> all news is on all mediums.  We should have the same information going
> to all of these and let the user choose which method they like for
> getting news.

The critical difference between improving our existing mediums, and the
emerge --news approach that I've proposed, is that emerge --news is the
only approach that actively pushes news out to *all* users, and puts it
in a place that is as guaranteed as anything else available to catch
their attention.

All the other approaches rely on the user going somewhere to get news,
whether it's signing up to a mailing list, reading www.g.o, reading the
forums, or whatever.  Inevitably, this is only going to reach a smaller
subsection of our user community.

What I care about is that we've taken the right steps to put important
information in front of *all* of our users (and our devs!).  Even
(especially?) the ones who are unable to keep up with the news as it is
currently delivered.

Making sure our users are well-informed improves the level and quality
of service that we provide; it can only enhance our reputation; and it
should also cut down on the amount of developer time that goes into
post-upgrade support (leaving more time for package maintenance).

Best regards,
Stu
-- 
Stuart Herbert                                         stuart@gentoo.org
Gentoo Developer                                  http://www.gentoo.org/
                                              http://stu.gnqs.org/diary/

GnuGP key id# F9AFC57C available from http://pgp.mit.edu
Key fingerprint = 31FB 50D4 1F88 E227 F319  C549 0C2F 80BA F9AF C57C
--

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Nathan L. Adams]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Stuart Herbert wrote:
> On Tue, 2005-11-01 at 14:51 -0500, Chris Gianelloni wrote:
> 
>>Did you specifically ask them if it is because we have different news in
>>different locations?  Somehow I think you're obscuring some facts to
>>make your own argument.
> 
> 
> That seems an unpleasant accusation to make :(
> 
> The answer is that I didn't ask them if it was because we have different
> news in different locations.  The question didn't occur to me.
> 
> 
>>The only problem that we have now with our multiple mediums is that not
>>all news is on all mediums.  We should have the same information going
>>to all of these and let the user choose which method they like for
>>getting news.
> 
> 
> The critical difference between improving our existing mediums, and the
> emerge --news approach that I've proposed, is that emerge --news is the
> only approach that actively pushes news out to *all* users, and puts it
> in a place that is as guaranteed as anything else available to catch
> their attention.
> 
> All the other approaches rely on the user going somewhere to get news,
> whether it's signing up to a mailing list, reading www.g.o, reading the
> forums, or whatever.  Inevitably, this is only going to reach a smaller
> subsection of our user community.
> 
> What I care about is that we've taken the right steps to put important
> information in front of *all* of our users (and our devs!).  Even
> (especially?) the ones who are unable to keep up with the news as it is
> currently delivered.
> 
> Making sure our users are well-informed improves the level and quality
> of service that we provide; it can only enhance our reputation; and it
> should also cut down on the amount of developer time that goes into
> post-upgrade support (leaving more time for package maintenance).
> 

One source: http://errata.gentoo.org/

Push that out to as many alternate sources as you like (RSS feeds,
summaries in emerge --news, forums post, etc.), but make it known that
the website is *the* source (your alternate sources should point back to
it).
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)

iD8DBQFDarUL2QTTR4CNEQARAh0pAKCi7BJpBOkRRT4iiaXUjajwbrjseACfahPV
R2MVvKhkLfnid1/ADRUZAxk=
=Oou4
-----END PGP SIGNATURE-----
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Sami Näätänen]

On Friday 04 November 2005 03:10, Nathan L. Adams wrote:
> Stuart Herbert wrote:
> > On Tue, 2005-11-01 at 14:51 -0500, Chris Gianelloni wrote:
> >>Did you specifically ask them if it is because we have different
> >> news in different locations?  Somehow I think you're obscuring
> >> some facts to make your own argument.
> >
> > That seems an unpleasant accusation to make :(
> >
> > The answer is that I didn't ask them if it was because we have
> > different news in different locations.  The question didn't occur
> > to me.
> >
> >>The only problem that we have now with our multiple mediums is that
> >> not all news is on all mediums.  We should have the same
> >> information going to all of these and let the user choose which
> >> method they like for getting news.
> >
> > The critical difference between improving our existing mediums, and
> > the emerge --news approach that I've proposed, is that emerge
> > --news is the only approach that actively pushes news out to *all*
> > users, and puts it in a place that is as guaranteed as anything
> > else available to catch their attention.
> >
> > All the other approaches rely on the user going somewhere to get
> > news, whether it's signing up to a mailing list, reading www.g.o,
> > reading the forums, or whatever.  Inevitably, this is only going to
> > reach a smaller subsection of our user community.
> >
> > What I care about is that we've taken the right steps to put
> > important information in front of *all* of our users (and our
> > devs!).  Even (especially?) the ones who are unable to keep up with
> > the news as it is currently delivered.
> >
> > Making sure our users are well-informed improves the level and
> > quality of service that we provide; it can only enhance our
> > reputation; and it should also cut down on the amount of developer
> > time that goes into post-upgrade support (leaving more time for
> > package maintenance).
>
> One source: http://errata.gentoo.org/
>
> Push that out to as many alternate sources as you like (RSS feeds,
> summaries in emerge --news, forums post, etc.), but make it known
> that the website is *the* source (your alternate sources should point
> back to it).

Well I don't like web so much for this kind of things, so fails me.
I want the info where I need it. I don't have network access from all 
the machines I admin. So the best possible repository for the news is 
with the tree, because that is allways required.
And because Gentoo has the control over the tree it is very trivial and 
secure way to spread the news.
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Xavier Neys]

Nathan L. Adams wrote:
> One source: http://errata.gentoo.org/
> 
> Push that out to as many alternate sources as you like (RSS feeds,
> summaries in emerge --news, forums post, etc.), but make it known that
> the website is *the* source (your alternate sources should point back to
> it).

I beg to differ. The tree should be the central point because it's the only 
known place where all users can receive relevant information on and for each 
and every system they maintain right before they upgrade.
The warning and the logic that triggers its display should be part of Portage.
Sometimes, all that would need to be displayed is "run foo to fix bar" or 
"Please do read http://bleh _before_ you upgrade foo".

If an "Upgrade guide to foo/bar for Gentoo" is required, you need an author to 
write it, not extra code or an extra web site.

-- 
/  Xavier Neys
\_ Gentoo Documentation Project
/  French & Internationalisation Lead
\  http://www.gentoo.org/doc/en
/\
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Jason Stubbs]

On Friday 04 November 2005 23:26, Xavier Neys wrote:
> Nathan L. Adams wrote:
> > One source: http://errata.gentoo.org/
> >
> > Push that out to as many alternate sources as you like (RSS feeds,
> > summaries in emerge --news, forums post, etc.), but make it known that
> > the website is *the* source (your alternate sources should point back to
> > it).
>
> I beg to differ. The tree should be the central point because it's the only
> known place where all users can receive relevant information on and for
> each and every system they maintain right before they upgrade.
> The warning and the logic that triggers its display should be part of
> Portage. Sometimes, all that would need to be displayed is "run foo to fix
> bar" or "Please do read http://bleh _before_ you upgrade foo".
>
> If an "Upgrade guide to foo/bar for Gentoo" is required, you need an author
> to write it, not extra code or an extra web site.

I probably shouldn't have included the sarcastic comment in my only other 
reply to this thread, but the rest of it was completely serious. People are 
under the mistaken impression that the ebuild tree is required to use 
portage. This is wrong and will become more and more wrong as time goes by.

If there is not a specific need for this news stuff to go into the tree then 
it shouldn't be there. If there is a specific need (ie. it is tied to 
packages) what difference is there to the existing ChangeLog?

--
Jason Stubbs
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Alec Joseph Warner]

Jason Stubbs wrote:
> On Friday 04 November 2005 23:26, Xavier Neys wrote:
> 
>>Nathan L. Adams wrote:
>>
>>>One source: http://errata.gentoo.org/
>>>
>>>Push that out to as many alternate sources as you like (RSS feeds,
>>>summaries in emerge --news, forums post, etc.), but make it known that
>>>the website is *the* source (your alternate sources should point back to
>>>it).
>>
>>I beg to differ. The tree should be the central point because it's the only
>>known place where all users can receive relevant information on and for
>>each and every system they maintain right before they upgrade.
>>The warning and the logic that triggers its display should be part of
>>Portage. Sometimes, all that would need to be displayed is "run foo to fix
>>bar" or "Please do read http://bleh _before_ you upgrade foo".
>>
>>If an "Upgrade guide to foo/bar for Gentoo" is required, you need an author
>>to write it, not extra code or an extra web site.
> 
> 
> I probably shouldn't have included the sarcastic comment in my only other 
> reply to this thread, but the rest of it was completely serious. People are 
> under the mistaken impression that the ebuild tree is required to use 
> portage. This is wrong and will become more and more wrong as time goes by.
> 
> If there is not a specific need for this news stuff to go into the tree then 
> it shouldn't be there. If there is a specific need (ie. it is tied to 
> packages) what difference is there to the existing ChangeLog?
> 
> --
> Jason Stubbs

I am going to summarize a bit, and address your point.

Summary: people want small news tidbits to be distributed to all users. 
  Currently the suggestion is tree-based.  Portage should have code to 
detect news elements after a sync and copy relevant elements to a uesr 
specified news directory.  The news should be in a human readable format 
(XML, RST, pig latin, don't care at this point see below).  Portage 
should post-sync, print a message noting the number of unread but 
relevant news messages.  Users can use whatever means of reading them 
that they like.  IMHO, emerge --news can go to hell in a handbasket, I'd 
rather just friggin use less, but hey, if you write the code...

News messages should contain minimal information necessary to carry 
relevant information including affected packages, and a link to some 
sort of documentation, be it gentoo-wiki, or official package docs, or 
whatever.

For those without internet access 24/7, there may be an option required 
to fetch these links.  In the case of say, dial-up where someone only 
has network say, 4 hours a day, they may wish to sync their tree, and 
spider the docs links so they may view them locally.  Machines with no 
outside network ( internal production servers ) may also wish to make 
use of this.  In the case of online guides, we cannot necessarily define 
their content, it may be XML, it may be plain text.  I do not see how 
conceeding that a user may need a web browser SOMEWHERE, is that big of 
a tradeoff, especially if the content is already locally available.

As far as including news in the tree goes, news is repository bound 
information.  Each repository may in fact have relevant news, and in 
preparation for multiple repositories this is how the news should be 
handled.  It goes with the rest of the repo-specific information.  That 
is why it should be in the tree.

However, in the case of a remote tree, some extra API calls may be 
required.  However, it is up to the class implementor to implement those 
calls, not the original portage team ( unless you want to support remote 
trees yourself, in which case that duty falls to you ).  The only other 
thing was no tree but a binpkg repo, in which case in savior, binpkg 
repo should have news elements build in ( a repo, just all built 
packages ).  In stable, news should probably be added to the binpackage 
if it's listed in the packages-affected.

For the XML vs RST.  I personally don't want to read XML files in a 
console, or install anything that makes it look all pretty for me, RST 
is plenty good enough.  Since Ciaran has graciously written all the code 
for it already, I don't see any reason not to use it.  RST is pretty 
simple to migrate to a new format anyhow, and a converter could be 
easily whipped up to transform it to guideXMl for errate.g.o if that is 
what is desired ( not a bad idea IMHO ).

I forgot one other thing, that being perhaps a red NEWS that shows up 
next to affected packages during an emerge -pv <package>, informing you 
that important news is available for a package you are about to install.

So yeah, this is a long thread :0

Alec Warner (Antarus)
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Jason Stubbs]

On Saturday 05 November 2005 03:53, Alec Joseph Warner wrote:
> As far as including news in the tree goes, news is repository bound
> information.  Each repository may in fact have relevant news, and in
> preparation for multiple repositories this is how the news should be
> handled.  It goes with the rest of the repo-specific information.  That
> is why it should be in the tree.

I seem to be repeating myself... What's an example of repository-specific 
non-package-specific news? Why does `emerge --changelog` not suffice for 
package-specific news?

--
Jason Stubbs
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Alec Warner]

Jason Stubbs wrote:
> On Saturday 05 November 2005 03:53, Alec Joseph Warner wrote:
> 
>>As far as including news in the tree goes, news is repository bound
>>information.  Each repository may in fact have relevant news, and in
>>preparation for multiple repositories this is how the news should be
>>handled.  It goes with the rest of the repo-specific information.  That
>>is why it should be in the tree.
> 
> 
> I seem to be repeating myself... What's an example of repository-specific 
> non-package-specific news? Why does `emerge --changelog` not suffice for 
> package-specific news?
> 
> --
> Jason Stubbs

Ok so I'm pwned there ;)

emerge --changelog has no 'official' format.  I believe echangelog
actually puts the changes in the correct format for emerge -l to read,
however not everyone uses echangelog.  Many developers commit in an
incompatable syntax causing the parsing to fail.  This I believe, is an
implementation issue.  Obviously if someone is trying to get an upgrade
guide to users they aren't going to commit in an incompatable format.

We had a similar discussion before and many people wanted gentoo
changelogs to stay true to only gentoo changes, thus some think a gentoo
changelog is an inappropriate place to look for upgrade guides and
errata.  Changelogs are also not easy to search through and the current
syntax does not provide all the benifits of the syntax provided by GLEP 42.

So the options for using emerge --changelog are basically, updating the
syntax to make it useful, probably audit the changelog code in emerge to
make sure it works better ( even half decent 'entries' aren't grabbed,
but I haven't looked at the changelog code in months ).  This of course
makes emerge the newsreader you didn't want, although I'm sure the
eselect module could be modified to read Changelog's just as easily.

Also, nothing covers the expiration of Changelog contents vs expiration
of news items, since the news items are file independent, what if a
bunch of commits basically erases a relevant news item out of the changelog?

Certainly I would support either way ( news or changelog ) although in
the latter case there are some seperate issues that need to be worked
out ( mostly policy issues ).
-- 
gentoo-dev@gentoo.org mailing list

[gentoo-dev] Re: Re: GLEP 42 (Was: Getting Important Updates To Users)

[Duncan]

Jason Stubbs posted <200511051408.09014.jstubbs@gentoo.org>, excerpted
below,  on Sat, 05 Nov 2005 14:08:08 +0900:

> On Saturday 05 November 2005 03:53, Alec Joseph Warner wrote:
>> As far as including news in the tree goes, news is repository bound
>> information.  Each repository may in fact have relevant news, and in
>> preparation for multiple repositories this is how the news should be
>> handled.  It goes with the rest of the repo-specific information.  That
>> is why it should be in the tree.
> 
> I seem to be repeating myself... What's an example of repository-specific 
> non-package-specific news? Why does `emerge --changelog` not suffice for 
> package-specific news?

I'd say it's a matter of degree, or we'd not be having the discussion.

Ideally, there's a changelog entry for /every/ commit.  The specified
purpose of "news" is to convey out-of-the-ordinary changes, where the
Gentoo user (aka Gentoo system sysadmin) needs to be aware of something
unusual, and likely take extraordinary steps to manage the upgrade.
Certainly, "stable on X arch" a bunch of times as a bunch of changelog
entries do not qualify as "out-of-the-ordinary", yet that's the sort of
documentation of changes one expects to fine in a changelog, tho they
would only be "noise" in the proposed "news" system, and shouldn't
generate news messages at all.

Perhaps this is something that needs further clarification in the GLEP?

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master -- 
and if you use the program, he is your master." Richard Stallman in
http://www.linuxdevcenter.com/pub/a/linux/2004/12/22/rms_interview.html


-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Michiel de Bruijne]

On Saturday 05 November 2005 06:08, Jason Stubbs wrote:
> Why does `emerge --changelog` not suffice for package-specific news?

>From a user/sys.admin point of view let me give you an example;

I maintain quite a lot Gentoo-systems. For me it's impossible to read _every_ 
changelog for minor release changes. For example not so long ago Apache was 
upgraded from 2.0.54-r15 to 2.0.54-r31. For me as a user/sys.admin based on 
versionnumbers this is a minor change. However the changes were rather 
extensive (e.g. reorganization of conf.files). 

When these changes occur I want to be informed _before_ I start emerge and I 
think that this information should be _pushed_ to users/sys.admins instead of 
_pulled_ from external sources (forums, website, mailinglist, etc. or 
changelogs).

If changelogs could be extended with a priority flag and emerge would notify 
me when a high priority changelog is applicable to my system then this would 
be just fine for me. Basically all I want is;

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 2 security advisories released for installed 
packages.
    * Type emerge --security to see the details.

    * Important: there are 5 unread news items.
    * Type emerge --help news to learn how to read news files.

If this is possible by extending the changelog I'm a happy users/sys.admin. I 
don't care if I need to type emerge --news or emerge --changelog as long the 
information is pushed.


Disclaimer; I'm not 100% sure that the versionnumbers from Apache mentioned 
above are exact the real world examples, but you get the idea.

Regards,

-- 
gentoo-dev@gentoo.org mailing list

[gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[R Hill]

Jason Stubbs wrote:

> I seem to be repeating myself... What's an example of repository-specific 
> non-package-specific news? Why does `emerge --changelog` not suffice for 
> package-specific news?

a) maintainers don't put important news in their changelogs.

there are a few exceptions.  gregkh's udev bumps, for example, always 
come with an explanation of what changes have been made and what to 
watch out for.  but mostly all the info you're going to get is "Version 
bump.", if that.

b) there's no way to separate the wheat from the chaff.

while i could (and usually do) emerge every update with -l, it's not 
something anyone with a life would do.  the signal to noise ratio is 
very low, and not many people are going to go through reading the 
changelogs for every package on the odd chance that there might be some 
important nugget of info they need to know.  combine this with a) and 
you'd have better luck playing the lottery than getting pertinent 
information that specifically applies to you.

c) it's a passive system

the user has to actually make an effort to retrieve this news.  we 
_already_ have a number of different sources that they could be getting 
important info from.  another is not what's needed.  what we're looking 
for is a proactive solution where the news is dropped at their feet 
below a bigass neon arrow saying READ ME.

d) news isn't necessarily package-based.

news items could be based on a user's profile, language preference, 
architecture, USE flags, etc.  there could also be general news to the 
entire community about global changes in Gentoo.


--de.

-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Paul de Vrieze]

[-- Attachment #1: Type: text/plain, Size: 1138 bytes --]

On Saturday 05 November 2005 06:34, Alec Warner wrote:
>
> emerge --changelog has no 'official' format.  I believe echangelog
> actually puts the changes in the correct format for emerge -l to read,
> however not everyone uses echangelog.  Many developers commit in an
> incompatable syntax causing the parsing to fail.  This I believe, is an
> implementation issue.  Obviously if someone is trying to get an upgrade
> guide to users they aren't going to commit in an incompatable format.

I would also like to add that the changelog has too much information to be 
usefull as a news source. In all honesty, when I'm emerging a new version 
of a package I'm not interested in keyword bumps, small cosmetic changes, 
added auxiliary scripts or documentation. These are all documented (and 
should be) in the changelog. If I update my system however, I'm mainly 
interested in knowing whether something is going to break. News would be 
a way to provide this knowledge to a user in an as concise as possible 
way.

Paul

-- 
Paul de Vrieze
Gentoo Developer
Mail: pauldv@gentoo.org
Homepage: http://www.devrieze.net

[-- Attachment #2: Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Jason Stubbs]

On Monday 07 November 2005 19:11, Paul de Vrieze wrote:
> On Saturday 05 November 2005 06:34, Alec Warner wrote:
> > emerge --changelog has no 'official' format.  I believe echangelog
> > actually puts the changes in the correct format for emerge -l to read,
> > however not everyone uses echangelog.  Many developers commit in an
> > incompatable syntax causing the parsing to fail.  This I believe, is an
> > implementation issue.  Obviously if someone is trying to get an upgrade
> > guide to users they aren't going to commit in an incompatable format.
>
> I would also like to add that the changelog has too much information to be
> usefull as a news source. In all honesty, when I'm emerging a new version
> of a package I'm not interested in keyword bumps, small cosmetic changes,
> added auxiliary scripts or documentation. These are all documented (and
> should be) in the changelog. If I update my system however, I'm mainly
> interested in knowing whether something is going to break. News would be
> a way to provide this knowledge to a user in an as concise as possible
> way.

So what's the point of the ChangeLog again? Move load from the CVS server and 
onto the rsync servers? (Don't answer that - just beating a dead horse ;)

I'm really just against having it in emerge, especially with the current 
suggestion of portage just doing a little bit of maintenance work for 
external tools and nothing else.

--
Jason Stubbs
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Grant Goodyear]

[-- Attachment #1: Type: text/plain, Size: 1922 bytes --]

Jason Stubbs wrote: [Mon Nov 07 2005, 06:37:10AM CST]
> So what's the point of the ChangeLog again? Move load from the CVS
> server and onto the rsync servers? (Don't answer that - just beating a
> dead horse ;)

*Grin*  I'm going to answer anyway, since the answer isn't necessarily
obvious to everybody.  Once upon a time, the expectation was that the
ChangeLog contained information about package modifications that would
be of interest to users, while the CVS log would contain info mainly of
interest to devs.  Of course, that was when viewcvs accessed the live
tree, too.  Since then, there seems to have been a consensus that the
CVS log should really be autogenerated from the ChangeLog, which itself
is created using ``echangelog``.  My view is that the ChangeLog should
contain user-readable descriptions (although we also encourage some
useful jargon such as "version bump") of every change a package has
undergone, providing a fairly complete history for that package that is 
much more readable than iterating through CVS diffs.  Consequently, the
ChangeLog has far too much information to realistically serve as a
low-noise news source.  (One could imagine tagging certain ChangeLog
entries as being particularly important, but that forces news to be
package based, and seems overly complicated, so please forget that I
ever brought it up.)

> I'm really just against having it in emerge, especially with the current 
> suggestion of portage just doing a little bit of maintenance work for 
> external tools and nothing else.

I'm not sure exactly what you're arguing here.  Is it just that you
think that the news stuff should be a post-sync hook instead of being
triggered explicitly by "emerge"?  

-g2boojum-
-- 
Grant Goodyear	
Gentoo Developer
g2boojum@gentoo.org
http://www.gentoo.org/~g2boojum
GPG Fingerprint: D706 9802 1663 DEF5 81B0  9573 A6DC 7152 E0F6 5B76

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Stuart Herbert]

[-- Attachment #1: Type: text/plain, Size: 1614 bytes --]

On Mon, 2005-11-07 at 21:37 +0900, Jason Stubbs wrote:
> So what's the point of the ChangeLog again?

Isn't it to record specific changes that have happened to a specific
package?

News items may be about changes that have not yet happened - to allow
users to plan ahead and prepare appropriately.

News items may also be about (possibly future) changes where there is no
one corresponding package; equally a news item may be relevant for a
large number of packages.  In both of those circumstances, looking for
news in a package-specific ChangeLog doesn't seem right to me.  Feels to
me to be both bad engineering and bad SCM practice.

> I'm really just against having it in emerge, especially with the current 
> suggestion of portage just doing a little bit of maintenance work for 
> external tools and nothing else.

I can't think of any other place where we have every Gentoo user's
attention to the same extent that we do when emerge outputs that
reminder about any CONFIG_PROTECTed packages that need attention.

It's the one and only place where we can reach every user.  That is the
whole purpose of this idea.  We're trying to deliver the news to 100% of
the user base, or as near as damn it.

Best regards,
Stu
-- 
Stuart Herbert                                         stuart@gentoo.org
Gentoo Developer                                  http://www.gentoo.org/
                                              http://stu.gnqs.org/diary/

GnuGP key id# F9AFC57C available from http://pgp.mit.edu
Key fingerprint = 31FB 50D4 1F88 E227 F319  C549 0C2F 80BA F9AF C57C
--

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Re: GLEP 42 (Was: Getting Important Updates To Users)

[Jason Stubbs]

On Tuesday 08 November 2005 01:06, Grant Goodyear wrote:
> Jason Stubbs wrote: [Mon Nov 07 2005, 06:37:10AM CST]
> > I'm really just against having it in emerge, especially with the current
> > suggestion of portage just doing a little bit of maintenance work for
> > external tools and nothing else.
>
> I'm not sure exactly what you're arguing here.  Is it just that you
> think that the news stuff should be a post-sync hook instead of being
> triggered explicitly by "emerge"?

I just wrote several paragraphs but that got me thinking so I deleted 'em.

Ok. There's two levels of APIs here. There's the post-sync stuff which 
utilizes portage's API. There'll never be any need for portage to utilize the 
post-sync stuff that I can think of; if there is, that's a reason for putting 
it into portage. The second layer is between the post-sync stuff and the news 
readers. Here we have a problem.

As Brian mentioned, multiple independent repositories will be supported and 
each should be allowed to have it's own independent set of news items. 
Multiple repositories will bring new (or completely replace) portage APIs. 
Hence, the post-sync stuff will have to accomodate. Yet, that's going to 
propogate into the post-sync component's API provided for the readers.

Multiple independent repositories is just one change that we know is going to 
throw a spanner in the works. There'll likely be others. Hmm, I think I've 
just discovered what's unsettling about all this. We're being asked to throw 
something into portage that'll do XYZ to support external tools, yet we are 
guaranteed to break the XYZ.

I guess I'd be happy with portage doing it and responsibility for 
compatibility staying with portage as long as we can decide/lead how the 
external tools gains access to the information.

--
Jason Stubbs
-- 
gentoo-dev@gentoo.org mailing list