Re: [OE-core] [PATCH 1/5] meta/conf/templates/default/conf-description.txt: add a template description

[Richard Purdie <richard.purdie@linuxfoundation.org>]

On Wed, 2024-01-31 at 13:39 +0100, Alexander Kanavin wrote:
> Existing conf-notes.txt is not adequate in situations where the user
> needs to select a config template from several, or get an overview of them and
> is interested only in a brief explanation of what the template is for,
> but not extended multi-paragraph instructions for how to use it.
> 
> Such descriptions can be provided via conf-description.txt and
> this patch adds such a description for the oe-core default template.
> 
> Updates to the tools and a tool for selecting templates which
> will make specific use of the description will follow.
> 
> Signed-off-by: Alexander Kanavin <alex@linutronix.de>
> ---
>  meta/conf/templates/default/conf-description.txt | 1 +
>  1 file changed, 1 insertion(+)
>  create mode 100644 meta/conf/templates/default/conf-description.txt
> 
> diff --git a/meta/conf/templates/default/conf-description.txt b/meta/conf/templates/default/conf-description.txt
> new file mode 100644
> index 00000000000..e49172fa0ce
> --- /dev/null
> +++ b/meta/conf/templates/default/conf-description.txt
> @@ -0,0 +1 @@
> +This is the default build configuration for the openembedded-core layer.

I know this feedback is long delayed so my apologies for that.

I think I'm ok with the idea of this but I believe the naming isn't
quite right.

"notes" does suggest something longer, so that is fine. My worry is
that in the metadata we have the SUMMARY and DESCRIPTION variables. The
former is the short one, the latter is the longer.

If developers see:

conf-notes.txt
conf-description.txt

then they don't know which is the "short" one.

If you however you have:

conf-notes.txt
conf-summary.txt

then I think that is much clearer?

I think I'm therefore ok with the idea but I'd like to suggest using
"summary" instead of "description"...

Cheers

Richard