Re: [docs] [PATCH v2 1/4] migration/release-notes-5.1: document oeqa/selftest envvars change

[Quentin Schulz <quentin.schulz@cherry.de>]

Hi Antonin,

On 10/1/24 12:09 PM, Antonin Godard wrote:
> [You don't often get email from antonin.godard@bootlin.com. Learn why 
> this is important at https://aka.ms/LearnAboutSenderIdentification ]
> 
> Hi Quentin,
> 
> On 01/10/2024 11:40, Quentin Schulz via lists.yoctoproject.org wrote:
>> Hi Yoann,
>>
>> On 9/28/24 12:00 AM, Yoann Congal via lists.yoctoproject.org wrote:
>>> From: Yoann Congal <yoann.congal@smile.fr>
>>>
>>> This covers the Poky commit:
>>> 61186bc98a5 (oeqa/selftest: Only rewrite envvars paths that absolutely
>>> point to builddir, 2024-09-10)
>>>
>>> Signed-off-by: Yoann Congal <yoann.congal@smile.fr>
>>> ---
>>> v1->v2: Reviews from Quentin Schulz:
>>> * environnement -> environment
>>> * oeqa/selftest now only rewrite*s*
>>> * Add exemples for the selftest change
>>> ---
>>>   documentation/migration-guides/migration-5.1.rst  | 15 +++++++++++++++
>>>   .../migration-guides/release-notes-5.1.rst        |  2 ++
>>>   2 files changed, 17 insertions(+)
>>>
>>> diff --git a/documentation/migration-guides/migration-5.1.rst
>>> b/documentation/migration-guides/migration-5.1.rst
>>> index b43fecc2d..4625ff0e1 100644
>>> --- a/documentation/migration-guides/migration-5.1.rst
>>> +++ b/documentation/migration-guides/migration-5.1.rst
>>> @@ -141,3 +141,18 @@ QEMU changes
>>>   Miscellaneous changes
>>>   ~~~~~~~~~~~~~~~~~~~~~
>>> +-  oeqa/selftest now only rewrites environment variable paths that
>>> absolutely
>>> +   point to builddir (i.e ``X=$BUILDDIR/conf/`` is still rewritten to
>>> point to
>>> +   the selftest ``conf/`` directory but not
>>> ``Y=$BUILDDIR/../bitbake/`` which
>>> +   still point to the ``bitbake/`` directory)
>>> +
>>> +   For example (taken from autobuilder environment): ``BB_LOGCONFIG``
>>> is an
>>
>> nit: could use :term:`BB_LOGCONFIG` here since we have it defined in the
>> reference manual? We could probably even avoid explaining what it means
>> here (not necessarily though).
> 
> Good catch, you can indeed use :term:`BB_LOGCONFIG` and avoid explaining
> its purpose.
> 
>>> +   Environment variables containing relative paths from tested build
>>> directory
>>> +   to outside of the original build directory may need to be updated
>>> as they
>>> +   won't be changed by selftest.
>>
>> selftest should be single-tick-quoted as defined as standard in the git
>> repo, c.f.
>> https://eur02.safelinks.protection.outlook.com/? 
>> url=https%3A%2F%2Fgit.yoctoproject.org%2Fyocto- 
>> docs%2Ftree%2Fdocumentation%2Fstandards.md&data=05%7C02%7Cquentin.schulz%40cherry.de%7Cd86b9396dbb24e6bb9a408dce2012bb1%7C5e0e1b5221b54e7b83bb514ec460677e%7C0%7C0%7C638633741917208894%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=MqJFRj5%2FMNumviLU168shE0bsiL84%2B5BqcPvHKV9q5M%3D&reserved=0
>>
>> This was done by Michael but he's not the maintainer anymore so I guess
>> whoever replaces him may have a different opinion, in which case
>> extending or replacing it would be most welcome, is that you Antonin
> 
> Indeed, I am slowly replacing Michael in this role and getting familiar
> with the documentation details. I'm also writing the release note for

Welcome to the community! And thanks for taking maintainership of the 
docs, it's always nice to have someone looking after it, regardless of 
the project.

> the next release at the moment (will send a series of patch this week
> hopefully).
> 
> Thanks for your reviews, they also help. As for selftest, I haven't seen
> it referenced with single-tick quotes elsewhere, unless you meant double
> ticks for code?
> 

I think what we discussed at the time with Michael was basically that 
anything that isn't an English word, or is but shouldn't be understood 
as one in the context (e.g. truncate as in the tool and not the English 
word) should be highlighted so that people don't confuse it with the 
English word.

I think this is what we meant in the standards file here: 
https://git.yoctoproject.org/yocto-docs/tree/documentation/standards.md#n79

Note that these were rules Michael/we came up with for new contributions 
to the docs, because we knew updating everything to match the standards 
would take a long time.

I still remember reading every page of the docs during the migration to 
Sphinx and I am not ready to do this again any time soon :) So patching 
when stumbling upon things that don't match the standard while reading 
the docs and enforcing it for new contributions made sense at the time.

Anyway, that's process and standards, they need to make sense to the 
maintainer and the community, and can evolve over time, so up to you, 
just putting out there the history and "current" state of affairs :)

Since 5.1 is supposed to be out soonish, maybe something to be picky 
about after the release is done ;) Up to you!

Cheers,
Quentin