1. Forum
  2. Usenet
  3. LINUX.GENTOO.DEV

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

    From Sam James@21:1/5 to All on Tue Oct 5 20:30:01 2021
    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 <[email protected]>
    ---
    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 <[email protected]>
    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
  • From Mike Gilbert@21:1/5 to [email protected] on Tue Oct 5 21:20:02 2021
    On Tue, Oct 5, 2021 at 2:27 PM Sam James <[email protected]> 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.

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Wolfgang E. Sanyer@21:1/5 to [email protected] on Tue Oct 5 21:50:02 2021
    On Tue, Oct 5, 2021 at 3:10 PM Mike Gilbert <[email protected]> wrote:

    On Tue, Oct 5, 2021 at 2:27 PM Sam James <[email protected]> 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.

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Andreas K. Huettel@21:1/5 to All on Wed Oct 6 00:17:33 2021
    Copy: [email protected] (Wolfgang E. Sanyer)


    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
    [email protected]
    Gentoo Linux developer
    (council, toolchain, base-system, perl, libreoffice)
    -----BEGIN PGP SIGNATURE-----
    Version: GnuPG v2

    iQKTBAABCgB9FiEE6W4INB9YeKX6Qpi1TEn3nlTQogYFAmFczv1fFIAAAAAALgAo aXNzdWVyLWZwckBub3RhdGlvbnMub3BlbnBncC5maWZ0aGhvcnNlbWFuLm5ldEU5 NkUwODM0MUY1ODc4QTVGQTQyOThCNTRDNDlGNzlFNTREMEEyMDYACgkQTEn3nlTQ ogY3XhAAnPCcuI2YvoZy8TdfEIm4/wqbzvsa3ZP3Yj18KTF7lgJS9bPDgC6jtznG wjNgJ0A5fFYIfZEezEw65hMQyrpZne2xEVw0Lmqzeb6usE3wfDq+0gdWt6QCJiS/ M7Z+BrdyrRGxmhVpO+8eQ14QLbuiDRkJZRMDXccZInr/wt3w/lRLyHa1zZ5yyify GHpwOKP0vWr87lzCXKugwvwgFUJ5xoGWlhsRkDmchMN0C9xUkttNvFyv0qLiXig4 HwdL9aGIcFKmIt/E8Oty7FLjdsPn+EN9rtSE0akLSSuyQeUSaYresaf2AM7I3Dmh VXzPkcbsfmC5rYWJPQJnl27YODmyUWnQ7ZLtUrjqsmsxXCl2TtmijKXYVziyfoPa fRVM7VJmiloOPzaN2klv93Hmm41RbWyQBnH5oCdNdyWDi+bm8hR66eYAASVqeO9Z zdWbMEg3R2twjLQsuVb4RwK2VnezkEwWlRfywcWqY8nB9qZa1pMmuP9rGiO7Cya2 Xu6e/4BbW/flay7mcU8Ho7UeY9iPX6+NlDBeUuspR280gUb61MEo06ZAEjz+ccn0 +h+ZmbdWUTNIlHk0vI7OwPA8KrSbR0YMEnSkkiQiU+Wxd+kFgxKYWrM7
  • From Ulrich Mueller@21:1/5 to All on Wed Oct 6 07:40:01 2021
    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

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)