"Required Variables" aren't really "required"

"Required Variables" aren't really "required"

[Robert P. J. Day]

here:

https://docs.yoctoproject.org/contributor-guide/recipe-style-guide.html#required-variables

the section "Required Variables" goes on to say that four variables
"should" be included in all recipes ("should" does not equal "must"),
but a quick test build showed that none of those four variables seemed
to be required for successful parsing -- only a missing "LICENSE"
triggered a parse error during my testing.

rday

Re: [docs] "Required Variables" aren't really "required"

[Antonin Godard]

On Fri Jun 5, 2026 at 1:40 PM CEST, Robert P. J. Day wrote:
>
> here:
>
> https://docs.yoctoproject.org/contributor-guide/recipe-style-guide.html#required-variables
>
> the section "Required Variables" goes on to say that four variables
> "should" be included in all recipes ("should" does not equal "must"),
> but a quick test build showed that none of those four variables seemed
> to be required for successful parsing -- only a missing "LICENSE"
> triggered a parse error during my testing.

What do you suggest as an alternative word for "Required"?

Antonin

Re: [docs] "Required Variables" aren't really "required"

[Robert P. J. Day]

On Fri, 5 Jun 2026, Antonin Godard via lists.yoctoproject.org wrote:

> On Fri Jun 5, 2026 at 1:40 PM CEST, Robert P. J. Day wrote:
> >
> > here:
> >
> > https://docs.yoctoproject.org/contributor-guide/recipe-style-guide.html#required-variables
> >
> > the section "Required Variables" goes on to say that four variables
> > "should" be included in all recipes ("should" does not equal "must"),
> > but a quick test build showed that none of those four variables seemed
> > to be required for successful parsing -- only a missing "LICENSE"
> > triggered a parse error during my testing.
>
> What do you suggest as an alternative word for "Required"?

  Well, it makes no sense to first say that short list of variables is
"Required", then say they "should" be included in all recipes. It's
common usage that "should" means only that something is *recommended*
or *encouraged*, not mandatory.

  Then based on my testing, none of those variables are actually
required since leaving them out didn't cause a parse error. So I don't
know how people would want to word that or what it should say.

rday

Re: [docs] "Required Variables" aren't really "required"

[Richard Purdie]

On Fri, 2026-06-05 at 07:22 -0700, Robert P. J. Day via lists.yoctoproject.org wrote:
> On Fri, 5 Jun 2026, Antonin Godard via lists.yoctoproject.org wrote:
> 
> > On Fri Jun 5, 2026 at 1:40 PM CEST, Robert P. J. Day wrote:
> > > 
> > > here:
> > > 
> > > https://docs.yoctoproject.org/contributor-guide/recipe-style-guide.html#required-variables
> > > 
> > > the section "Required Variables" goes on to say that four variables
> > > "should" be included in all recipes ("should" does not equal "must"),
> > > but a quick test build showed that none of those four variables seemed
> > > to be required for successful parsing -- only a missing "LICENSE"
> > > triggered a parse error during my testing.
> > 
> > What do you suggest as an alternative word for "Required"?
> 
>   Well, it makes no sense to first say that short list of variables is
> "Required", then say they "should" be included in all recipes. It's
> common usage that "should" means only that something is *recommended*
> or *encouraged*, not mandatory.
> 
>   Then based on my testing, none of those variables are actually
> required since leaving them out didn't cause a parse error. So I don't
> know how people would want to word that or what it should say.

LICENSE is effectively required and should be in the required section.
SUMMARY/DESCRIPTION are also strongly encouraged else they get defaults
which aren't particularly useful. I thought there were QA checks for
those? Perhaps the QA tests are limited just to oe-core by default?

I think saying they're required is fine to be honest. LICENSE should be
moved to the required section.

HOMEPAGE is also strongly recommended, again. Perhaps the section
should be:

"""
The following variables should be included in all recipes:

LICENSE, DESCRIPTION, SUMMARY

It is also strongly recommended to set:

HOMEPAGE, BUGTRACKER
"""

Would that be more acceptable to you?

Cheers,

Richard

Re: [docs] "Required Variables" aren't really "required"

[Robert P. J. Day]

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

On Fri, 5 Jun 2026, Richard Purdie wrote:

> On Fri, 2026-06-05 at 07:22 -0700, Robert P. J. Day via lists.yoctoproject.org wrote:
> > On Fri, 5 Jun 2026, Antonin Godard via lists.yoctoproject.org wrote:
> >
> > > On Fri Jun 5, 2026 at 1:40 PM CEST, Robert P. J. Day wrote:
> > > >
> > > > here:
> > > >
> > > > https://docs.yoctoproject.org/contributor-guide/recipe-style-guide.html#required-variables
> > > >
> > > > the section "Required Variables" goes on to say that four variables
> > > > "should" be included in all recipes ("should" does not equal "must"),
> > > > but a quick test build showed that none of those four variables seemed
> > > > to be required for successful parsing -- only a missing "LICENSE"
> > > > triggered a parse error during my testing.
> > >
> > > What do you suggest as an alternative word for "Required"?
> >
> >   Well, it makes no sense to first say that short list of variables is
> > "Required", then say they "should" be included in all recipes. It's
> > common usage that "should" means only that something is *recommended*
> > or *encouraged*, not mandatory.
> >
> >   Then based on my testing, none of those variables are actually
> > required since leaving them out didn't cause a parse error. So I don't
> > know how people would want to word that or what it should say.
>
> LICENSE is effectively required and should be in the required section.
> SUMMARY/DESCRIPTION are also strongly encouraged else they get defaults
> which aren't particularly useful. I thought there were QA checks for
> those? Perhaps the QA tests are limited just to oe-core by default?
>
> I think saying they're required is fine to be honest. LICENSE should be
> moved to the required section.
>
> HOMEPAGE is also strongly recommended, again. Perhaps the section
> should be:
>
> """
> The following variables should be included in all recipes:
>
> LICENSE, DESCRIPTION, SUMMARY
>
> It is also strongly recommended to set:
>
> HOMEPAGE, BUGTRACKER
> """
>
> Would that be more acceptable to you?

  i should point out that the same inconsistency about required versus
suggested occurs here:

https://docs.yoctoproject.org/contributor-guide/recipe-style-guide.html#patch-upstream-status

where it claims that the OE system "requires" patch upstream status,
but follows that up with that each patch "should" provide detailed
information. i deleted a few patch "Upstream-Status" lines and parsing
worked just fine.

  i'll shut up about this now.

rday

Re: [docs] "Required Variables" aren't really "required"

[Richard Purdie]

On Fri, 2026-06-05 at 11:12 -0400, Robert P. J. Day wrote:
>   i should point out that the same inconsistency about required versus
> suggested occurs here:
> 
> https://docs.yoctoproject.org/contributor-guide/recipe-style-guide.html#patch-upstream-status
> 
> where it claims that the OE system "requires" patch upstream status,
> but follows that up with that each patch "should" provide detailed
> information. i deleted a few patch "Upstream-Status" lines and parsing
> worked just fine.

I hinted at this but let me be more specific. Try a build ;-)

OE-Core definitely requires Upstream-Status.

Cheers,

Richard

Re: [docs] "Required Variables" aren't really "required"

[Robert P. J. Day]

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

On Fri, 5 Jun 2026, Richard Purdie wrote:

> On Fri, 2026-06-05 at 11:12 -0400, Robert P. J. Day wrote:
> >   i should point out that the same inconsistency about required versus
> > suggested occurs here:
> >
> > https://docs.yoctoproject.org/contributor-guide/recipe-style-guide.html#patch-upstream-status
> >
> > where it claims that the OE system "requires" patch upstream status,
> > but follows that up with that each patch "should" provide detailed
> > information. i deleted a few patch "Upstream-Status" lines and parsing
> > worked just fine.
>
> I hinted at this but let me be more specific. Try a build ;-)
>
> OE-Core definitely requires Upstream-Status.

  i did ... so non-OE-Core patches apparently have no such
requirement.

rday

Re: [docs] "Required Variables" aren't really "required"

[Richard Purdie]

On Fri, 2026-06-05 at 11:38 -0400, Robert P. J. Day wrote:
> On Fri, 5 Jun 2026, Richard Purdie wrote:
> 
> > On Fri, 2026-06-05 at 11:12 -0400, Robert P. J. Day wrote:
> > >   i should point out that the same inconsistency about required
> > > versus
> > > suggested occurs here:
> > > 
> > > https://docs.yoctoproject.org/contributor-guide/recipe-style-guide.html#patch-upstream-status
> > > 
> > > where it claims that the OE system "requires" patch upstream
> > > status,
> > > but follows that up with that each patch "should" provide
> > > detailed
> > > information. i deleted a few patch "Upstream-Status" lines and
> > > parsing
> > > worked just fine.
> > 
> > I hinted at this but let me be more specific. Try a build ;-)
> > 
> > OE-Core definitely requires Upstream-Status.
> 
>   i did ... so non-OE-Core patches apparently have no such
> requirement.

and did you try it with an OE-Core recipe?

Cheers,

Richard

Re: [docs] "Required Variables" aren't really "required"

[Robert P. J. Day]

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

On Fri, 5 Jun 2026, Richard Purdie via lists.yoctoproject.org wrote:

> On Fri, 2026-06-05 at 11:38 -0400, Robert P. J. Day wrote:
> > On Fri, 5 Jun 2026, Richard Purdie wrote:
> >
> > > On Fri, 2026-06-05 at 11:12 -0400, Robert P. J. Day wrote:
> > > > ￜ i should point out that the same inconsistency about required
> > > > versus
> > > > suggested occurs here:
> > > >
> > > > https://docs.yoctoproject.org/contributor-guide/recipe-style-guide.html#patch-upstream-status
> > > >
> > > > where it claims that the OE system "requires" patch upstream
> > > > status,
> > > > but follows that up with that each patch "should" provide
> > > > detailed
> > > > information. i deleted a few patch "Upstream-Status" lines and
> > > > parsing
> > > > worked just fine.
> > >
> > > I hinted at this but let me be more specific. Try a build ;-)
> > >
> > > OE-Core definitely requires Upstream-Status.
> >
> > ￜ i did ... so non-OE-Core patches apparently have no such
> > requirement.
>
> and did you try it with an OE-Core recipe?

  yup, and i was a bit surprised at the result (although i'm sure this
will come as no surprise to you).

  with wrynose release, i picked a random oe-core recipe (util-linux),
and edited the associated ptest.patch file to delete the line:

  Upstream-Status: Pending

i was surprised that if i simply wanted to generate the environment or
parse the recipe:

  $ bitbake -e util-linux
  $ bitbake -p util-linux

that worked fine, so i guess neither of those operations checks the
patches.

  predictably, this command:

  $ bitbake -c do_patch util-linux

generated:

  ERROR: util-linux-2.41.3-r0 do_patch: QA Issue: Missing Upstream-Status in patch

so that works just fine.

  in short, the necessity for upstream status applies only to oe-core
patches. should the docs mention that distinction?

rday

Re: [docs] "Required Variables" aren't really "required"

[Richard Purdie]

On Fri, 2026-06-05 at 12:32 -0400, Robert P. J. Day wrote:
>   yup, and i was a bit surprised at the result (although i'm sure this
> will come as no surprise to you).
> 
>   with wrynose release, i picked a random oe-core recipe (util-linux),
> and edited the associated ptest.patch file to delete the line:
> 
>   Upstream-Status: Pending
> 
> i was surprised that if i simply wanted to generate the environment or
> parse the recipe:
> 
>   $ bitbake -e util-linux
>   $ bitbake -p util-linux
> 
> that worked fine, so i guess neither of those operations checks the
> patches.
> 
>   predictably, this command:
> 
>   $ bitbake -c do_patch util-linux
> 
> generated:
> 
>   ERROR: util-linux-2.41.3-r0 do_patch: QA Issue: Missing Upstream-Status in patch
> 
> so that works just fine.
> 
>   in short, the necessity for upstream status applies only to oe-core
> patches. should the docs mention that distinction?

I went and checked and "patch-status" is being added to ERROR_QA
unconditionally so it should apply to other layers too, unless you've
something changing that locally (a layer or local config).

I do feel this discussion is off in the weeds but I really don't like
the docs being altered based on incorrect information.

Cheers,

Richard

Re: [docs] "Required Variables" aren't really "required"

[Robert P. J. Day]

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

On Fri, 5 Jun 2026, Richard Purdie wrote:

> On Fri, 2026-06-05 at 12:32 -0400, Robert P. J. Day wrote:
> >   yup, and i was a bit surprised at the result (although i'm sure this
> > will come as no surprise to you).
> >
> >   with wrynose release, i picked a random oe-core recipe (util-linux),
> > and edited the associated ptest.patch file to delete the line:
> >
> >   Upstream-Status: Pending
> >
> > i was surprised that if i simply wanted to generate the environment or
> > parse the recipe:
> >
> >   $ bitbake -e util-linux
> >   $ bitbake -p util-linux
> >
> > that worked fine, so i guess neither of those operations checks the
> > patches.
> >
> >   predictably, this command:
> >
> >   $ bitbake -c do_patch util-linux
> >
> > generated:
> >
> >   ERROR: util-linux-2.41.3-r0 do_patch: QA Issue: Missing Upstream-Status in patch
> >
> > so that works just fine.
> >
> >   in short, the necessity for upstream status applies only to oe-core
> > patches. should the docs mention that distinction?
>
> I went and checked and "patch-status" is being added to ERROR_QA
> unconditionally so it should apply to other layers too, unless you've
> something changing that locally (a layer or local config).
>
> I do feel this discussion is off in the weeds but I really don't like
> the docs being altered based on incorrect information.

  i will check why local layers seem to be treated differently.

rday

Re: [docs] "Required Variables" aren't really "required"

[Robert P. J. Day]

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

On Fri, 5 Jun 2026, Richard Purdie wrote:

> On Fri, 2026-06-05 at 07:22 -0700, Robert P. J. Day via lists.yoctoproject.org wrote:
> > On Fri, 5 Jun 2026, Antonin Godard via lists.yoctoproject.org wrote:
> >
> > > On Fri Jun 5, 2026 at 1:40 PM CEST, Robert P. J. Day wrote:
> > > >
> > > > here:
> > > >
> > > > https://docs.yoctoproject.org/contributor-guide/recipe-style-guide.html#required-variables
> > > >
> > > > the section "Required Variables" goes on to say that four variables
> > > > "should" be included in all recipes ("should" does not equal "must"),
> > > > but a quick test build showed that none of those four variables seemed
> > > > to be required for successful parsing -- only a missing "LICENSE"
> > > > triggered a parse error during my testing.
> > >
> > > What do you suggest as an alternative word for "Required"?
> >
> >   Well, it makes no sense to first say that short list of variables is
> > "Required", then say they "should" be included in all recipes. It's
> > common usage that "should" means only that something is *recommended*
> > or *encouraged*, not mandatory.
> >
> >   Then based on my testing, none of those variables are actually
> > required since leaving them out didn't cause a parse error. So I don't
> > know how people would want to word that or what it should say.
>
> LICENSE is effectively required and should be in the required section.
> SUMMARY/DESCRIPTION are also strongly encouraged else they get defaults
> which aren't particularly useful. I thought there were QA checks for
> those? Perhaps the QA tests are limited just to oe-core by default?
>
> I think saying they're required is fine to be honest. LICENSE should be
> moved to the required section.
>
> HOMEPAGE is also strongly recommended, again. Perhaps the section
> should be:
>
> """
> The following variables should be included in all recipes:
>
> LICENSE, DESCRIPTION, SUMMARY
>
> It is also strongly recommended to set:
>
> HOMEPAGE, BUGTRACKER
> """
>
> Would that be more acceptable to you?

  i'll post one more note on this and then let it go. as a test, i
tweaked the OE-Core "bc" recipe to see what was *truly* required for a
recipe in the openembedded-core layer, and here are the results which
differ slightly from what one reads here:

https://docs.yoctoproject.org/contributor-guide/recipe-style-guide.html#recipe-metadata

  in the "bc" recipe, i wiped out most of the metadata and learned
that parsing does indeed require the LICENSE and LIC_FILES_CHKSUM
fields (that section does not mention that LIC_FILES_CHKSUM is not
required if LICENSE is "CLOSED", but that is mentioned in the
variables glossary).

  beyond that, i deleted all of SUMMARY, HOMEPAGE, DESCRIPTION and
SECTION, ran "bitbake -p bc", and got only two warnings:


WARNING: bc-1.08.2-r0 do_recipe_qa: QA Issue: Recipe bc in
/home/rpjday/oe/layers/openembedded-core/meta/recipes-extended/bc/bc_1.08.2.bb
does not contain a SUMMARY. Please add an entry. [missing-metadata]
WARNING: bc-1.08.2-r0 do_recipe_qa: QA Issue: Recipe bc in
/home/rpjday/oe/layers/openembedded-core/meta/recipes-extended/bc/bc_1.08.2.bb
does not contain a HOMEPAGE. Please add an entry. [missing-metadata]


which are, in fact, the two metadata variables examined in
do_recipe_qa().

  and given the various defaults for stuff like SUMMARY and
DESCRIPTION and so on, it seems that LICENSE and LIC_FILES_CHKSUM is
the only *truly* required metadata, and everything else is simply
strongly encouraged or will be quietly set to a default value as
defined in bitbake.conf.

rday