[2/2] meta-poky/conf/templates/default/conf-description.txt: add a template description

There is a need to separate the template notes (which are lengthy
instructions about how to use the template) and template description
(which is a short explanation of what the template is for).

This patch adds such a description for the poky default template,
and updates to the tools will follow.

Signed-off-by: Alexander Kanavin <alex@linutronix.de>
---
 meta-poky/conf/templates/default/conf-description.txt | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 meta-poky/conf/templates/default/conf-description.txt

> -----Original Message-----
> From: poky@lists.yoctoproject.org <poky@lists.yoctoproject.org> On Behalf Of Alexander Kanavin
> Sent: den 30 augusti 2023 16:16
> To: poky@lists.yoctoproject.org
> Cc: Alexander Kanavin <alex@linutronix.de>
> Subject: [poky] [PATCH 2/2] meta-poky/conf/templates/default/conf-description.txt: add a template description
> 
> There is a need to separate the template notes (which are lengthy
> instructions about how to use the template) and template description
> (which is a short explanation of what the template is for).
> 
> This patch adds such a description for the poky default template,
> and updates to the tools will follow.
> 
> Signed-off-by: Alexander Kanavin <alex@linutronix.de>
> ---
>  meta-poky/conf/templates/default/conf-description.txt | 1 +
>  1 file changed, 1 insertion(+)
>  create mode 100644 meta-poky/conf/templates/default/conf-description.txt
> 
> diff --git a/meta-poky/conf/templates/default/conf-description.txt b/meta-poky/conf/templates/default/conf-description.txt
> new file mode 100644
> index 00000000000..8fc03030c7f
> --- /dev/null
> +++ b/meta-poky/conf/templates/default/conf-description.txt
> @@ -0,0 +1 @@
> +This is the default build configuration for the Poky reference distribution.
> --
> 2.30.2

To use the same nomenclature as for the variables, how about calling 
this conf-summary.txt instead? Compare to SUMMARY vs DESCRIPTION.

//Peter

On Thu, 31 Aug 2023 at 19:04, Peter Kjellerstedt
<peter.kjellerstedt@axis.com> wrote:
> > +++ b/meta-poky/conf/templates/default/conf-description.txt
> > @@ -0,0 +1 @@
> > +This is the default build configuration for the Poky reference distribution.
> > --
> > 2.30.2
>
> To use the same nomenclature as for the variables, how about calling
> this conf-summary.txt instead? Compare to SUMMARY vs DESCRIPTION.

To match them up we'd also have to rename conf-notes.txt, breaking
compatiblity. And the meanings are not the same as in
summary/description recipes or package metadata.

conf-notes.txt would contain lengthy instructions/notes for how to use
the template and would be shown when you actually set up a build
directory (this is already happening now), conf-description.txt has a
single sentence saying what it is for, and shown before/during
selection of the template.

Alex

> -----Original Message-----
> From: Alexander Kanavin <alex.kanavin@gmail.com>
> Sent: den 31 augusti 2023 19:12
> To: Peter Kjellerstedt <peter.kjellerstedt@axis.com>
> Cc: poky@lists.yoctoproject.org; Alexander Kanavin <alex@linutronix.de>
> Subject: Re: [poky] [PATCH 2/2] meta-poky/conf/templates/default/conf-description.txt: add a template description
> 
> On Thu, 31 Aug 2023 at 19:04, Peter Kjellerstedt <peter.kjellerstedt@axis.com> wrote:
> > > +++ b/meta-poky/conf/templates/default/conf-description.txt
> > > @@ -0,0 +1 @@
> > > +This is the default build configuration for the Poky reference distribution.
> > > --
> > > 2.30.2
> >
> > To use the same nomenclature as for the variables, how about calling
> > this conf-summary.txt instead? Compare to SUMMARY vs DESCRIPTION.
> 
> To match them up we'd also have to rename conf-notes.txt, breaking
> compatiblity. And the meanings are not the same as in
> summary/description recipes or package metadata.
> 
> conf-notes.txt would contain lengthy instructions/notes for how to use
> the template and would be shown when you actually set up a build
> directory (this is already happening now), conf-description.txt has a
> single sentence saying what it is for, and shown before/during
> selection of the template.
> 
> Alex

Well, your distinction between "notes" and "description" and that the 
latter is expected to be a oneliner is not obvious from their names.
Though, in the end, I guess it is all down to documentation...

//Peter

On Thu, 31 Aug 2023 at 21:10, Peter Kjellerstedt
<peter.kjellerstedt@axis.com> wrote:
> > conf-notes.txt would contain lengthy instructions/notes for how to use
> > the template and would be shown when you actually set up a build
> > directory (this is already happening now), conf-description.txt has a
> > single sentence saying what it is for, and shown before/during
> > selection of the template.
> Well, your distinction between "notes" and "description" and that the
> latter is expected to be a oneliner is not obvious from their names.
> Though, in the end, I guess it is all down to documentation...

There's also how the tools are handling them. 'bitbake-layers
save-build-conf' would write the following into the files:

https://patchwork.yoctoproject.org/project/oe-core/patch/20230830154314.661141-1-alex@linutronix.de/

Description would be then shown on template selection and both
description and notes when initializing a build from it. Between all
that users should be able to figure out what needs to go where.

Alex