[gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)

[gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)

[Sam James]

This is a preliminary version/draft of a proposed change to
GLEP 68.

I'd like to introduce a method for developers to signal anything
special about a package and how to correctly maintain it.

Sam James (1):
  glep-0068: Add notes element for package maintenance instructions

 glep-0068.rst | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

-- 
2.33.0

[gentoo-dev] [PATCH 1/1] glep-0068: Add notes element for package maintenance instructions

[Sam James]

This adds a new '<notes/>' element to allow maintainers to describe
package-specific quirks or other instructions on how to correctly
maintain a package. This is intended to encourage developers to document
knowledge and increase the bus-factor of packages which are delicate
but must live beyond a maintainer.

Signed-off-by: Sam James <sam@gentoo.org>
---
 glep-0068.rst | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

diff --git a/glep-0068.rst b/glep-0068.rst
index 83e54d9..21bdf2a 100644
--- a/glep-0068.rst
+++ b/glep-0068.rst
@@ -4,10 +4,10 @@ Title: Package and category metadata
 Author: Michał Górny <mgorny@gentoo.org>
 Type: Standards Track
 Status: Final
-Version: 1.1
+Version: 1.2
 Created: 2016-03-14
-Last-Modified: 2021-09-11
-Post-History: 2016-03-16, 2018-02-20
+Last-Modified: 2021-10-05
+Post-History: 2016-03-16, 2018-02-20, 2021-10-05
 Content-Type: text/x-rst
 Requires: 67
 Replaces: 34, 46, 56
@@ -160,6 +160,8 @@ element can contain, in any order:
   in different languages (at most one for each language), as detailed
   in `USE flag descriptions`_.
 
+- at most one ``<notes/>`` element containing notes on maintenance.
+
 - at most one ``<upstream/>`` element providing information on upstream
   of the package, as detailed in `Upstream descriptions`_.
 
@@ -213,6 +215,18 @@ The ``<use/>`` element can contain the following elements:
   which the description applies, and contains text, optionally interspersed
   with ``<cat/>`` and ``<pkg/>`` elements.
 
+Notes element
+~~~~~~~~~~~~~
+
+The ``<notes/>`` element describes important information on how to maintain
+a package.
+
+The ``<notes/>`` element has an obligatory ``type=""`` attribute whose value is
+can be either ``text`` or ``url``. If its value is ``text``, then the
+``<notes/>`` value is formed of multi-line text. If its value is ``url``, the
+``<notes/>`` value should be a link to a page containing information on how
+to correct maintain the package.
+
 Upstream descriptions
 ~~~~~~~~~~~~~~~~~~~~~
 The ``<upstream/>`` element provides information on the upstream of a package.
@@ -484,6 +498,12 @@ Example metadata.xml file
         <flag name='bar' restrict='&lt;dev-libs/foo-12'>Konfiguriert das Paket mit Unterstützung für bar (benötigt <pkg>dev-libs/bar</pkg>)</flag>
         <flag name='bar' restrict='&gt;=dev-libs/foo-12'>Konfiguriert das Paket mit Unterstützung für bar</flag>
       </use>
+      <notes type="text">
+          Almost every release involves checking a diff of the build system.
+          Be careful of bundled libfoo which sometimes has custom modifications.
+          Versioning scheme is unusual.
+          Track record of ABI breaks within minor releases: check!
+      </notes>
       <upstream>
         <maintainer status='active'>
           <email>upstream@example.com</email>
-- 
2.33.0

Re: [gentoo-dev] [PATCH 1/1] glep-0068: Add notes element for package maintenance instructions

[Mike Gilbert]

On Tue, Oct 5, 2021 at 2:27 PM Sam James <sam@gentoo.org> wrote:
>
> This adds a new '<notes/>' element to allow maintainers to describe
> package-specific quirks or other instructions on how to correctly
> maintain a package. This is intended to encourage developers to document
> knowledge and increase the bus-factor of packages which are delicate
> but must live beyond a maintainer.

Personally, I am much more likely to notice a comment at the top of
the ebuild than a new element in metadata.xml.

Re: [gentoo-dev] [PATCH 1/1] glep-0068: Add notes element for package maintenance instructions

[Wolfgang E. Sanyer]

On Tue, Oct 5, 2021 at 3:10 PM Mike Gilbert <floppym@gentoo.org> wrote:
>
> On Tue, Oct 5, 2021 at 2:27 PM Sam James <sam@gentoo.org> wrote:
> >
> > This adds a new '<notes/>' element to allow maintainers to describe
> > package-specific quirks or other instructions on how to correctly
> > maintain a package. This is intended to encourage developers to document
> > knowledge and increase the bus-factor of packages which are delicate
> > but must live beyond a maintainer.
>
> Personally, I am much more likely to notice a comment at the top of
> the ebuild than a new element in metadata.xml.

I generally agree that comments are more visible/noticeable than
metadata, however, I also think that this could be a good step forward
for overall maintainability. The issue with documenting these things
in comments is that the comment lives only within the specific version
of the ebuild in which it is authored: it is up to the maintainer to
carry those comments over when version bumping. While this is
generally not a problem due to copy/paste, I think it is messy - there
could be an update to the comment from one version to the next,
meaning I now have two version of the comment floating around.

With <note/>, there is one localized "source of truth" for this
documentation, which should remove any ambiguity.

I would hope that after launching the <note/> feature, there would be
a gradual (or sudden?!) shift away from the current comments towards
the <note/> tag, maybe even including this in the dev manual.

Re: [gentoo-dev] [PATCH 1/1] glep-0068: Add notes element for package maintenance instructions

[Andreas K. Huettel]

[-- Attachment #1: Type: text/plain, Size: 1170 bytes --]

> 
> I generally agree that comments are more visible/noticeable than
> metadata, however, I also think that this could be a good step forward
> for overall maintainability. The issue with documenting these things
> in comments is that the comment lives only within the specific version
> of the ebuild in which it is authored: it is up to the maintainer to
> carry those comments over when version bumping. While this is
> generally not a problem due to copy/paste, I think it is messy - there
> could be an update to the comment from one version to the next,
> meaning I now have two version of the comment floating around.
> 
> With <note/>, there is one localized "source of truth" for this
> documentation, which should remove any ambiguity.
> 
> I would hope that after launching the <note/> feature, there would be
> a gradual (or sudden?!) shift away from the current comments towards
> the <note/> tag, maybe even including this in the dev manual.
> 

That makes no sense, since the notes could be version-dependent.

-- 
Andreas K. Hüttel
dilfridge@gentoo.org
Gentoo Linux developer
(council, toolchain, base-system, perl, libreoffice)

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 981 bytes --]

Re: [gentoo-dev] [PATCH 1/1] glep-0068: Add notes element for package maintenance instructions

[Ulrich Mueller]

>>>>> On Tue, 05 Oct 2021, Sam James wrote:
 
> +Notes element
> +~~~~~~~~~~~~~
> +
> +The ``<notes/>`` element describes important information on how to maintain
> +a package.
> +
> +The ``<notes/>`` element has an obligatory ``type=""`` attribute whose value is
> +can be either ``text`` or ``url``. If its value is ``text``, then the

Too many verbs ("is can be") in this sentence.

> +``<notes/>`` value is formed of multi-line text. If its value is ``url``, the
> +``<notes/>`` value should be a link to a page containing information on how
> +to correct maintain the package.

Since this is plain text, it presumably should have an optional "lang"
attribute for consistency with other elements.

Ulrich

Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)

[Michał Górny]

On Tue, 2021-10-05 at 19:27 +0100, Sam James wrote:
> This is a preliminary version/draft of a proposed change to
> GLEP 68.
> 
> I'd like to introduce a method for developers to signal anything
> special about a package and how to correctly maintain it.
> 
> Sam James (1):
>   glep-0068: Add notes element for package maintenance instructions
> 
>  glep-0068.rst | 26 +++++++++++++++++++++++---
>  1 file changed, 23 insertions(+), 3 deletions(-)
> 

To be honest, I don't think adding it to metadata.xml is a good idea. 
This is not something that's going to be machine-parseable,
and expecting people to look into metadata.xml to see if it's even
present is a bit much.

Maybe we could just add README files to the package directories
in question.  This would have the clear advantage that the files will be
immediately visible.

-- 
Best regards,
Michał Górny

Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)

[Alessandro Barbieri]

[-- Attachment #1: Type: text/plain, Size: 255 bytes --]

> Maybe we could just add README files to the package directories
> in question.  This would have the clear advantage that the files will be
> immediately visible.
>

I'll personally prefer a readme.
Also almost all metadata.xml features are underused

>

[-- Attachment #2: Type: text/html, Size: 673 bytes --]

Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 1084 bytes --]

>>>>> On Tue, 05 Oct 2021, Michał Górny wrote:

> On Tue, 2021-10-05 at 19:27 +0100, Sam James wrote:
>> This is a preliminary version/draft of a proposed change to
>> GLEP 68.
>> 
>> I'd like to introduce a method for developers to signal anything
>> special about a package and how to correctly maintain it.
>> 
>> Sam James (1):
>> glep-0068: Add notes element for package maintenance instructions
>> 
>> glep-0068.rst | 26 +++++++++++++++++++++++---
>> 1 file changed, 23 insertions(+), 3 deletions(-)

> To be honest, I don't think adding it to metadata.xml is a good idea. 
> This is not something that's going to be machine-parseable,
> and expecting people to look into metadata.xml to see if it's even
> present is a bit much.

The same argument would apply to longdescription.

> Maybe we could just add README files to the package directories
> in question.  This would have the clear advantage that the files will be
> immediately visible.

Scattering a package's metadata across multiple files doesn't look like
a good idea to me.

Ulrich

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]

Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)

[Matthew Marchese]

On 10/5/21 12:09, Michał Górny wrote:
> On Tue, 2021-10-05 at 19:27 +0100, Sam James wrote:
>> This is a preliminary version/draft of a proposed change to
>> GLEP 68.
>>
>> I'd like to introduce a method for developers to signal anything
>> special about a package and how to correctly maintain it.
>>
>> Sam James (1):
>>    glep-0068: Add notes element for package maintenance instructions
>>
>>   glep-0068.rst | 26 +++++++++++++++++++++++---
>>   1 file changed, 23 insertions(+), 3 deletions(-)
>>
> To be honest, I don't think adding it to metadata.xml is a good idea.
> This is not something that's going to be machine-parseable,
> and expecting people to look into metadata.xml to see if it's even
> present is a bit much.
>
> Maybe we could just add README files to the package directories
> in question.  This would have the clear advantage that the files will be
> immediately visible.
>
Some of the devs use their username or project pages on the wiki for 
maintainers notes. That's a decent place to keep them since there is not 
an in-source place, but truly the closer the documentation can be kept 
to the source the better.

I also like the idea of markdown files or RST files living in gentoo::. 
I personally find RST to be a bit more challenging to write, but it's 
simple enough to learn and we 'already have RST to HTML conversion on 
www.g.o for GLEPs. GitHub will render either file format in browser. Not 
sure about all the other Git* sites.

Apparently the MD and RST formats are somewhat interchangeable if one 
does not go too crazy on formatting: 
https://gist.github.com/javiertejero/4585196

Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 1022 bytes --]

>>>>> On Thu, 07 Oct 2021, Matthew Marchese wrote:

> I also like the idea of markdown files or RST files living in
> gentoo::. I personally find RST to be a bit more challenging to write,
> but it's simple enough to learn and we 'already have RST to HTML
> conversion on www.g.o for GLEPs. GitHub will render either file format
> in browser. Not sure about all the other Git* sites.

> Apparently the MD and RST formats are somewhat interchangeable if one
> does not go too crazy on formatting: 
> https://gist.github.com/javiertejero/4585196

To add to this, here are two excellent articles comparing the two
formats:

https://www.zverovich.net/2016/06/16/rst-vs-markdown.html
https://eli.thegreenplace.net/2017/restructuredtext-vs-markdown-for-technical-d$

Given that we already use RST elsewhere and that it is well supported by
docutils (and our own docutils-glep), that's the format I'd personally
prefer.

Otherwise, the picture in the first article pretty much summarizes it.
:)

Ulrich

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]

Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)

[Alec Warner]

I thought we were going to go with the github-pages type route
(markdown, rendered online or locally.)

-A

On Tue, Oct 5, 2021 at 11:28 AM Sam James <sam@gentoo.org> wrote:
>
> This is a preliminary version/draft of a proposed change to
> GLEP 68.
>
> I'd like to introduce a method for developers to signal anything
> special about a package and how to correctly maintain it.
>
> Sam James (1):
>   glep-0068: Add notes element for package maintenance instructions
>
>  glep-0068.rst | 26 +++++++++++++++++++++++---
>  1 file changed, 23 insertions(+), 3 deletions(-)
>
> --
> 2.33.0
>
>

Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)

[Sam James]

[-- Attachment #1: Type: text/plain, Size: 949 bytes --]



> On 5 Oct 2021, at 21:29, Alec Warner <antarus@gentoo.org> wrote:
> 
> I thought we were going to go with the github-pages type route
> (markdown, rendered online or locally.)
> 

So, the thinking was, we could allow somewhat shorthand
notes or for the people who want to invest more time, allow
the GitHub-pages type route.

But I'm open to the idea of just recommending people
use that if there's no appetite for mixed types.

> -A
> 
> On Tue, Oct 5, 2021 at 11:28 AM Sam James <sam@gentoo.org> wrote:
>> 
>> This is a preliminary version/draft of a proposed change to
>> GLEP 68.
>> 
>> I'd like to introduce a method for developers to signal anything
>> special about a package and how to correctly maintain it.
>> 
>> Sam James (1):
>>  glep-0068: Add notes element for package maintenance instructions
>> 
>> glep-0068.rst | 26 +++++++++++++++++++++++---
>> 1 file changed, 23 insertions(+), 3 deletions(-)
>> 
>> --
>> 2.33.0
>> 
>> 
> 


[-- Attachment #2: Message signed with OpenPGP --]
[-- Type: application/pgp-signature, Size: 618 bytes --]

Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)

[Alec Warner]

On Tue, Oct 5, 2021 at 1:36 PM Sam James <sam@gentoo.org> wrote:
>
>
>
> > On 5 Oct 2021, at 21:29, Alec Warner <antarus@gentoo.org> wrote:
> >
> > I thought we were going to go with the github-pages type route
> > (markdown, rendered online or locally.)
> >
>
> So, the thinking was, we could allow somewhat shorthand
> notes or for the people who want to invest more time, allow
> the GitHub-pages type route.
>
> But I'm open to the idea of just recommending people
> use that if there's no appetite for mixed types.

I'd argue we can add NOTES.md to packages (e.g. allow those files.)
Then we modify packages.gentoo.org to render the markdown; or users
can render locally or read unrendered.

WDYT?

-A

>
> > -A
> >
> > On Tue, Oct 5, 2021 at 11:28 AM Sam James <sam@gentoo.org> wrote:
> >>
> >> This is a preliminary version/draft of a proposed change to
> >> GLEP 68.
> >>
> >> I'd like to introduce a method for developers to signal anything
> >> special about a package and how to correctly maintain it.
> >>
> >> Sam James (1):
> >>  glep-0068: Add notes element for package maintenance instructions
> >>
> >> glep-0068.rst | 26 +++++++++++++++++++++++---
> >> 1 file changed, 23 insertions(+), 3 deletions(-)
> >>
> >> --
> >> 2.33.0
> >>
> >>
> >
>

Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 310 bytes --]

>>>>> On Tue, 05 Oct 2021, Alec Warner wrote:

> I'd argue we can add NOTES.md to packages (e.g. allow those files.)
> Then we modify packages.gentoo.org to render the markdown; or users
> can render locally or read unrendered.

How would you deal with translations? One NOTES file for every language?

Ulrich

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]

Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)

[Alec Warner]

On Tue, Oct 5, 2021 at 10:37 PM Ulrich Mueller <ulm@gentoo.org> wrote:
>
> >>>>> On Tue, 05 Oct 2021, Alec Warner wrote:
>
> > I'd argue we can add NOTES.md to packages (e.g. allow those files.)
> > Then we modify packages.gentoo.org to render the markdown; or users
> > can render locally or read unrendered.
>
> How would you deal with translations? One NOTES file for every language?
>
> Ulrich

The notes files are for devs, not for users. Do we have non-english
speaking developers?

-A

Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 415 bytes --]

>>>>> On Wed, 06 Oct 2021, Alec Warner wrote:

> On Tue, Oct 5, 2021 at 10:37 PM Ulrich Mueller <ulm@gentoo.org> wrote:
>> How would you deal with translations? One NOTES file for every language?

> The notes files are for devs, not for users. Do we have non-english
> speaking developers?

Sure, this is a legitimate point. But it's an explicit design decision,
not something that can be silently assumed.

Ulrich

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]

Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)

[Ionen Wolkens]

[-- Attachment #1: Type: text/plain, Size: 1048 bytes --]

On Tue, Oct 05, 2021 at 02:21:22PM -0700, Alec Warner wrote:
> I'd argue we can add NOTES.md to packages (e.g. allow those files.)
> Then we modify packages.gentoo.org to render the markdown; or users
> can render locally or read unrendered.
> 
> WDYT?

Given this topic came up again on IRC, late reply to say that some
kind NOTES of file in the tree is my preference over metadata.xml
at the moment.

I don't feel strongly about being rendered somewhere though, a dev
will see the file in the tree if they work on the package (partly
because of that I'd also rather rst over md for bit better plain-text
readability, but can work with either). Seeing the file is main reason
I prefer this over metadata.xml, making it clear there's notes without
needing any tools integration to parse metadata.xml and remind about.

fwiw given these are entirely for devs they could even be skipped
from sync mirrors so users don't get them and think it's something
they need to read (+less files), but no strong opinion here.

-- 
ionen

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)

[Joonas Niilola]

[-- Attachment #1.1: Type: text/plain, Size: 1604 bytes --]

On 4.3.2022 2.35, Ionen Wolkens wrote:
> On Tue, Oct 05, 2021 at 02:21:22PM -0700, Alec Warner wrote:
>> I'd argue we can add NOTES.md to packages (e.g. allow those files.)
>> Then we modify packages.gentoo.org to render the markdown; or users
>> can render locally or read unrendered.
>>
>> WDYT?
> 
> Given this topic came up again on IRC, late reply to say that some
> kind NOTES of file in the tree is my preference over metadata.xml
> at the moment.
> 
> I don't feel strongly about being rendered somewhere though, a dev
> will see the file in the tree if they work on the package (partly
> because of that I'd also rather rst over md for bit better plain-text
> readability, but can work with either). Seeing the file is main reason
> I prefer this over metadata.xml, making it clear there's notes without
> needing any tools integration to parse metadata.xml and remind about.
> 
> fwiw given these are entirely for devs they could even be skipped
> from sync mirrors so users don't get them and think it's something
> they need to read (+less files), but no strong opinion here.
> 

make.conf:
FEATURES="bumpnotes"

or make.conf:
BUMPNOTES=y

then .ebuild:
BUMPNOTES=1

or
has_version sys-apps/portage[gentoo-dev]

results in:
"QA notice:
This package has internal version bump notes. Please see..."

and do those notes get saved to metadata.xml?

Because I doubt people will get to the habit of checking metadata.xml
manually for each bump. But we all test the packages we merge ":^)" and
therefore would see this QA notice. Or ewarn.

-- juippis

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 618 bytes --]

Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)

[Joshua Kinard]

On 10/5/2021 16:29, Alec Warner wrote:
> I thought we were going to go with the github-pages type route
> (markdown, rendered online or locally.)
> 
> -A
> 
> On Tue, Oct 5, 2021 at 11:28 AM Sam James <sam@gentoo.org> wrote:
>>
>> This is a preliminary version/draft of a proposed change to
>> GLEP 68.
>>
>> I'd like to introduce a method for developers to signal anything
>> special about a package and how to correctly maintain it.
>>
>> Sam James (1):
>>   glep-0068: Add notes element for package maintenance instructions
>>
>>  glep-0068.rst | 26 +++++++++++++++++++++++---
             ^^^^

Or perhaps we could use RST formatting like the GLEP source there to keep
the plain text form readable, but also support visual rendering into HTML if
needed?

>>  1 file changed, 23 insertions(+), 3 deletions(-)
>>
>> --
>> 2.33.0
>>


-- 
Joshua Kinard
Gentoo/MIPS
kumba@gentoo.org
rsa6144/5C63F4E3F5C6C943 2015-04-27
177C 1972 1FB8 F254 BAD0 3E72 5C63 F4E3 F5C6 C943

"The past tempts us, the present confuses us, the future frightens us.  And
our lives slip away, moment by moment, lost in that vast, terrible in-between."

--Emperor Turhan, Centauri Republic