| Message ID | 20240131123908.1098544-1-alex@linutronix.de |
|---|---|
| State | New |
| Headers | show |
| Series | [1/5] meta/conf/templates/default/conf-description.txt: add a template description | expand |
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
On Thu, 15 Feb 2024 at 16:00, Richard Purdie <richard.purdie@linuxfoundation.org> wrote: > 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"... No problem. Peter suggested this previously as well, but I didn't think it's super important back then. Alex
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.
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