Request for Reviews and future package updates

Request for Reviews and future package updates

[Mark Hatle]

I'd like to request that future reviews and package updates include "SUMMARY"
information in the recipe files.

For people who are not aware of the issue, a policy was created in Yocto 0.9
that we want each package to contain both a summary and description.  The
summary should be short and fewer then 80 characters if possible.  While the
description may be arbitrarily long and should explain the functionality of the
package.

By default, the SUMMARY is set to equal the DESCRIPTION if it was not previously
set.

So if the DESCRIPTION is short, a SUMMARY may not be required, such as:

DESCRIPTION = "A multi-purpose linux bootloader"


However, in a package with a more complicated description, such as chrpath:

DESCRIPTION = "chrpath allows you to change the rpath (where the application \
looks for libraries) in an application. It does not (yet) allow you to add an \
rpath if there isn't one already."

A short summary should be added to the recipe:

SUMMARY = "Tool to edit rpath in ELF binaries"

---

I'm currently going through Poky updating many of the recipes by updating
descriptions as necessary and adding SUMMARY fields.  In the future, or as
packages are updated, we should ensure that both the SUMMARY and DESCRIPTION are
present and up-to-date.

--Mark

Re: Request for Reviews and future package updates

[Richard Purdie]

On Thu, 2010-11-18 at 16:34 -0600, Mark Hatle wrote:
> I'd like to request that future reviews and package updates include "SUMMARY"
> information in the recipe files.
> 
> For people who are not aware of the issue, a policy was created in Yocto 0.9
> that we want each package to contain both a summary and description.  The
> summary should be short and fewer then 80 characters if possible.  While the
> description may be arbitrarily long and should explain the functionality of the
> package.
> 
> By default, the SUMMARY is set to equal the DESCRIPTION if it was not previously
> set.
> 
> So if the DESCRIPTION is short, a SUMMARY may not be required, such as:
> 
> DESCRIPTION = "A multi-purpose linux bootloader"
> 
> 
> However, in a package with a more complicated description, such as chrpath:
> 
> DESCRIPTION = "chrpath allows you to change the rpath (where the application \
> looks for libraries) in an application. It does not (yet) allow you to add an \
> rpath if there isn't one already."
> 
> A short summary should be added to the recipe:
> 
> SUMMARY = "Tool to edit rpath in ELF binaries"
> 
> ---
> 
> I'm currently going through Poky updating many of the recipes by updating
> descriptions as necessary and adding SUMMARY fields.  In the future, or as
> packages are updated, we should ensure that both the SUMMARY and DESCRIPTION are
> present and up-to-date.

It would be nice to have a section in the wiki with the minimum recipe
requirements documented. We certainly have some but I'm not sure
everything is written down in one place?

Cheers,

Richard

Re: Request for Reviews and future package updates

[Mark Hatle]

On 11/19/10 6:08 AM, Richard Purdie wrote:
> On Thu, 2010-11-18 at 16:34 -0600, Mark Hatle wrote:
> 
> It would be nice to have a section in the wiki with the minimum recipe
> requirements documented. We certainly have some but I'm not sure
> everything is written down in one place?

Any suggestion as to where to start this documentation process in the Wiki?  I'm
more then happy to create the topic and start editing it with the SUMMARY and
DESCRIPTION information.

--Mark

> Cheers,
> 
> Richard
> 

Re: Request for Reviews and future package updates

[Darren Hart]

On 11/19/2010 04:08 AM, Richard Purdie wrote:
> On Thu, 2010-11-18 at 16:34 -0600, Mark Hatle wrote:
>> I'd like to request that future reviews and package updates include "SUMMARY"
>> information in the recipe files.
>>
>> For people who are not aware of the issue, a policy was created in Yocto 0.9
>> that we want each package to contain both a summary and description.  The
>> summary should be short and fewer then 80 characters if possible.  While the
>> description may be arbitrarily long and should explain the functionality of the
>> package.
>>
>> By default, the SUMMARY is set to equal the DESCRIPTION if it was not previously
>> set.
>>
>> So if the DESCRIPTION is short, a SUMMARY may not be required, such as:
>>
>> DESCRIPTION = "A multi-purpose linux bootloader"
>>
>>
>> However, in a package with a more complicated description, such as chrpath:
>>
>> DESCRIPTION = "chrpath allows you to change the rpath (where the application \
>> looks for libraries) in an application. It does not (yet) allow you to add an \
>> rpath if there isn't one already."
>>
>> A short summary should be added to the recipe:
>>
>> SUMMARY = "Tool to edit rpath in ELF binaries"
>>
>> ---
>>
>> I'm currently going through Poky updating many of the recipes by updating
>> descriptions as necessary and adding SUMMARY fields.  In the future, or as
>> packages are updated, we should ensure that both the SUMMARY and DESCRIPTION are
>> present and up-to-date.
>
> It would be nice to have a section in the wiki with the minimum recipe
> requirements documented. We certainly have some but I'm not sure
> everything is written down in one place?

There is already a section in the handbook on adding recipes, wouldn't 
it make sense to make those examples complete and mention which fields 
are required?

-- 
Darren Hart
Yocto Linux Kernel