Re: [docs] [PATCH v2 3/5] ref-manual/terms.rst: simplify the Source Directory definition

["Antonin Godard" <antonin.godard@bootlin.com>]

Hi,

On Tue Jan 20, 2026 at 5:42 PM CET, Quentin Schulz via lists.yoctoproject.org wrote:
> Hi Antonin,
>
> On 1/20/26 4:17 PM, Antonin Godard via lists.yoctoproject.org wrote:
>> Now that we no longer have Poky around, simplify the Source Directory
>> definition:
>> 
>> - Make references to existing documents that show how to create this
>>    Source Directory.
>> 
>> - This directory contains sources, the layout in which they are
>>    presented does not matter so much, as it can be different and/or
>>    freeform depending on whether we use bitbake-setup or not.
>> 
>>    The definition chooses "project" as the name of the source directory
>>    and is the one that should be used when showing examples in the
>>    documentation.
>> 
>>    A typical Source Directory would look like the following:
>> 
>>    project/
>>    ├── build/
>>    └── layers/
>> 
>> Other parts of the documentation referencing to this as the Poky
>> repository still have to be updated.
>> 
>> This will also mean that this definition will be used a lot less across
>> the documentation: in most cases, when the "Source Directory" is
>> referenced as the Poky repository, it can be replaced by
>> OpenEmbedded-Core, Bitbake, the documentation, or meta-yocto. We'll keep
>
> Not really? The Source Directory will be project/layers/ no?

No, even though I do find it confusing too to call it Source Directory, it is
meant to represent the whole project/ directory as a whole. It was probably more
meaningful when poky was there as poky was some source itself.

We could rename this term by something else but that would mean replacing it
everywhere.

> [...]
>
>> -     For more information on concepts related to Git repositories,
>> -     branches, and tags, see the
>> -     ":ref:`overview-manual/development-environment:repositories, tags, and branches`"
>> -     section in the Yocto Project Overview and Concepts Manual.
>> +     The Source Directory contains BitBake, OpenEmbedded-Core (OE-Core),
>> +     Documentation, Metadata and other files that all support the Yocto Project.
>> +     Consequently, you must have the Source Directory in place on your
>> +     development system in order to do any development using the Yocto Project.
>>   
>
> You didn't discuss my feedback on v1 here and it's unchanged, so pasting 
> the same here:

I think I've missed it, sorry :/

> Isn't Metadata what we used to say about the content of OE-Core? This
> way of listing implies to me OE-Core isn't metadata (it is).

For me metadata is what OpenEmbedded-Core contains but could be
what meta-openembedded contains: it's recipes, classes, etc. But here I agree it
doesn't make sense to be listed.

> Also, it doesn't necessarily need to contain the Documentation (e.g. via
> a manual setup).

True, I'll remove it.

> Finally, we should probably also
>
> s/Source Directory/:term:`Source Directory`/

Thanks,
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com