clarify how bbappend files work with an unversioned BitBake recipe

Add a short note to the BitBake intro manual chapter to clarify that,
given an unversioned .bb recipe file, the matching .bbappend must also
be unversioned.

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>

---

Hi Robert,

Please Cc the bitbake ML as well. The Yocto docs community reviews the 
patches but it's up to the BitBake maintainer(s) to take the patch.

C.f. https://git.openembedded.org/bitbake/tree/README#n29

On 6/2/25 3:28 PM, Robert P. J. Day via lists.yoctoproject.org wrote:
> 
> Add a short note to the BitBake intro manual chapter to clarify that,
> given an unversioned .bb recipe file, the matching .bbappend must also
> be unversioned.
> 
> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> 
> ---
> 
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-intro.rst b/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
> index 539bb62d8..1c3faff0e 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
> @@ -272,6 +272,12 @@ append name would not match. However, if you named the append file
>   In the most general case, you could name the append file something as
>   simple as ``busybox_%.bbappend`` to be entirely version independent.
> 
> +.. note::
> +
> +   In the infrequent case of an unversioned BitBake recipe (such as
> +   ``linux-yocto-dev.bb``), the corresponding append file must be similarly
> +   unversioned; that is, ``linux-yocto-dev.bbappend``.
> +

I wouldn't make this a note. There are a bunch of examples, all of which 
aren't in a note, so we should do the same here.

I could even see this being mentioned in an even sneakier way, e.g.:

"""
BitBake expects every append file to have a corresponding recipe file 
(e.g. ``formfactor.bb`` and ``formfactor.bbappend``).
"""

What follows in this paragraph is actually pretty explanatory I believe? 
"The append file and corresponding recipe file must use the same root 
filename. The filenames can only differ in the file type".

Though we contradict ourselves a few paragraphs below where we say we 
can use % to do some less strict matching :)

Cheers,
Quentin

On Mon Jun 2, 2025 at 3:28 PM CEST, Robert P. J. Day wrote:
>
> Add a short note to the BitBake intro manual chapter to clarify that,
> given an unversioned .bb recipe file, the matching .bbappend must also
> be unversioned.
>
> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
>
> ---
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-intro.rst b/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
> index 539bb62d8..1c3faff0e 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-intro.rst
> @@ -272,6 +272,12 @@ append name would not match. However, if you named the append file
>  In the most general case, you could name the append file something as
>  simple as ``busybox_%.bbappend`` to be entirely version independent.
>
> +.. note::
> +
> +   In the infrequent case of an unversioned BitBake recipe (such as
> +   ``linux-yocto-dev.bb``), the corresponding append file must be similarly
> +   unversioned; that is, ``linux-yocto-dev.bbappend``.
> +
>  Obtaining BitBake
>  =================

This needs to be sent to the bitbake-devel@lists.openembedded.org mailing list,
with this list in copy.

Thanks,
Antonin