RFC: fix summary text for lots of packages
 

The packaging guidelines have a single sentence on package summaries:
https://fedoraproject.org/wiki/Packaging/Guidelines#Summary_and_description

"The summary should be a short and concise description of the package"

Broken packages are a problem as PackageKit shows the summary first (in
bold) in preference to the package name. This is by design.

Quite a lot of packages have summary text that is overly verbose, and
this makes the GUI and output from pkcon look rubbish.

For instance, I've filed
https://bugzilla.redhat.com/show_bug.cgi?id=472365 where the oggconvert
package has a summary of:

"A simple GNOME application that converts media files to Free formats"

First, we don't need to say it's an application, not that it's GNOME
specific. Surely something like this would be better:

"Simple media converter"
or
"Simple conversion to free media formats"
or
"Simple media converter using free formats"

The guidelines also don't say if it should be Title Case or if the
summary should include the application name. If we come to some
guidelines (or working practices) on this email thread, I'll update the
wiki page with more details.

It would also be a good idea to have a few "shining examples" for people
to copy when creating new packages. When we've done that, I'll start
filing bugs.

Thanks,

Richard.


--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list

RFC: fix summary text for lots of packages
 

On Thu November 20 2008, Richard Hughes wrote:

> "A simple GNOME application that converts media files to Free formats"
>
> First, we don't need to say it's an application, not that it's GNOME
> specific. Surely something like this would be better:

If I understand you correctly, you say that the summary should not mention,
that it is GNOME specific, but in the bug report you write that this is a
good summary:

| GNOME Power Manager

Imho it is not bad to mention that an applications is GNOME / KDE / whatever
specific unless it is obvious from the package name. Also iirc the package
for the GNOME power manager is also named gnome-power-manager, so imho above
summary does not contain any additional useful information imho.

Regards,
Till
--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list

RFC: fix summary text for lots of packages
 

On Thu, Nov 20, 2008 at 02:33:27PM +0000, Richard Hughes wrote:
>The guidelines also don't say if it should be Title Case or if the
>summary should include the application name. If we come to some
>guidelines (or working practices) on this email thread, I'll update the
>wiki page with more details.

So, while I think packaging guidelines are good to have, I don't think
everything needs to be codified there. It just makes a reviewer's job
harder, and writing a guideline for this is going to be fairly tedious.

>It would also be a good idea to have a few "shining examples" for people
>to copy when creating new packages. When we've done that, I'll start
>filing bugs.

Just file bugs for packages you think are overly verbose. Offer
alternate summaries in the bug, and a URL to your email for
rationale.

josh

--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list

RFC: fix summary text for lots of packages
 

Josh Boyer (jwboyer@gmail.com) said:
> >It would also be a good idea to have a few "shining examples" for people
> >to copy when creating new packages. When we've done that, I'll start
> >filing bugs.
>
> Just file bugs for packages you think are overly verbose. Offer
> alternate summaries in the bug, and a URL to your email for
> rationale.

I'm not sure this scales across 5000 packages. So it would be good
to have at least *something* in the guidelines.

Bill

--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list

RFC: fix summary text for lots of packages
 

On Thu, 20 Nov 2008, Josh Boyer wrote:


On Thu, Nov 20, 2008 at 02:33:27PM +0000, Richard Hughes wrote:

The guidelines also don't say if it should be Title Case or if the
summary should include the application name. If we come to some
guidelines (or working practices) on this email thread, I'll update the
wiki page with more details.


So, while I think packaging guidelines are good to have, I don't think
everything needs to be codified there. It just makes a reviewer's job
harder, and writing a guideline for this is going to be fairly tedious.


It would also be a good idea to have a few "shining examples" for people
to copy when creating new packages. When we've done that, I'll start
filing bugs.


Just file bugs for packages you think are overly verbose. Offer
alternate summaries in the bug, and a URL to your email for
rationale.


+1
-sv

--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list

RFC: fix summary text for lots of packages
 

On Thu, 2008-11-20 at 09:56 -0500, Bill Nottingham wrote:
> Josh Boyer (jwboyer@gmail.com) said:
> > >It would also be a good idea to have a few "shining examples" for people
> > >to copy when creating new packages. When we've done that, I'll start
> > >filing bugs.
> >
> > Just file bugs for packages you think are overly verbose. Offer
> > alternate summaries in the bug, and a URL to your email for
> > rationale.
>
> I'm not sure this scales across 5000 packages. So it would be good
> to have at least *something* in the guidelines.

Well, the FPG is intentionally lax on %summary's, because we had wanted
to avoid getting lot in endless discussions on something which is
technically widely meaningness.

Ralf




--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list

RFC: fix summary text for lots of packages
 

On Thu, 2008-11-20 at 16:12 +0100, Ralf Corsepius wrote:
> On Thu, 2008-11-20 at 09:56 -0500, Bill Nottingham wrote:
> > Josh Boyer (jwboyer@gmail.com) said:
> > > >It would also be a good idea to have a few "shining examples" for people
> > > >to copy when creating new packages. When we've done that, I'll start
> > > >filing bugs.
> > >
> > > Just file bugs for packages you think are overly verbose. Offer
> > > alternate summaries in the bug, and a URL to your email for
> > > rationale.
> >
> > I'm not sure this scales across 5000 packages. So it would be good
> > to have at least *something* in the guidelines.
>
> Well, the FPG is intentionally lax on %summary's, because we had wanted
> to avoid getting lot in endless discussions on something which is
> technically widely meaningness.

Right, but maybe we could have a soft guideline such as:

* Summary should aim to be less than 8 words

Richard.


--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list

RFC: fix summary text for lots of packages
 

On Thu, 2008-11-20 at 15:19 +0000, Richard Hughes wrote:
> Right, but maybe we could have a soft guideline such as:
>
> * Summary should aim to be less than 8 words

Or even fewer than 8 words?

--
David Woodhouse Open Source Technology Centre
David.Woodhouse@intel.com Intel Corporation

--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list

RFC: fix summary text for lots of packages
 

Richard Hughes wrote:
> On Thu, 2008-11-20 at 16:12 +0100, Ralf Corsepius wrote:
>> On Thu, 2008-11-20 at 09:56 -0500, Bill Nottingham wrote:
>>> Josh Boyer (jwboyer@gmail.com) said:
>>>>> It would also be a good idea to have a few "shining examples" for people
>>>>> to copy when creating new packages. When we've done that, I'll start
>>>>> filing bugs.
>>>> Just file bugs for packages you think are overly verbose. Offer
>>>> alternate summaries in the bug, and a URL to your email for
>>>> rationale.
>>> I'm not sure this scales across 5000 packages. So it would be good
>>> to have at least *something* in the guidelines.
>> Well, the FPG is intentionally lax on %summary's, because we had wanted
>> to avoid getting lot in endless discussions on something which is
>> technically widely meaningness.
>
> Right, but maybe we could have a soft guideline such as:
>
> * Summary should aim to be less than 8 words
>
I generally dislike soft guidelines. Instead of the Packaging Committee
making a controversial decisions that contributors argue about, it
becomes the individual reviewers and packagers arguing about it on many
separate bugs....

Which is not to say that I wouldn't vote for such a thing, just that I
usually ask:
1) Why can this not be a hard guideline? (In this case, because it's
something that's better left to the packager).

2) Why should this be part of the review guidelines, then? (So one GUI
tool can better support its interface).

3) Does number 2 justify the arguments that packagers and reviewers are
going to get into and the bugs that will be opened about them? I'm not
so certain about this one... then again, I haven't opened up a GUI
package manager for over 6 months so....

What I would put into the Guidelines are the best practices and
suggestions you talk about. That way the review guidelines stay pretty
much the same but people can refer to the best practices for things that
make a good summary.

So instead of:
*Should*: a summary should aim to be less than eight words

we'd have a paragraph or page that describes the summary:

The summary is used by many GUI tools. Our main supported GUI tool
makes the summary more prominent than the package name because it is
often a better description for the end user to make a decision about
installing. To make the user's experience better here, we try to have
short, succinct summaries that don't repeat information in the name.

For instance, a good summary for gnome-power-manager would be "Gnome
Applets for setting power saving features"
The repetition of GNOME is good in this case because the applets *only*
run on the gnome panel.

A good summary for: [continue with other examples]

-Toshio

--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list

RFC: fix summary text for lots of packages
 

On Thu, Nov 20, 2008 at 09:56:28AM -0500, Bill Nottingham wrote:
>Josh Boyer (jwboyer@gmail.com) said:
>> >It would also be a good idea to have a few "shining examples" for people
>> >to copy when creating new packages. When we've done that, I'll start
>> >filing bugs.
>>
>> Just file bugs for packages you think are overly verbose. Offer
>> alternate summaries in the bug, and a URL to your email for
>> rationale.
>
>I'm not sure this scales across 5000 packages. So it would be good
>to have at least *something* in the guidelines.

You're assuming that all 5000 packages need fixing. I doubt that's
the case.

Also, the bugs need to be filed either way. So the scaling argument
still applies and adding a guideline for this is really just unneeded
work...

josh

--
fedora-devel-list mailing list
fedora-devel-list@redhat.com
https://www.redhat.com/mailman/listinfo/fedora-devel-list