Re: [gentoo-dev] [PATCH 1/1] glep-0068: Add notes element for package maintenance instructions
> On Tue, 05 Oct 2021, Sam James wrote:
> +Notes element
> +~
> +
> +The element describes important information on how to maintain
> +a package.
> +
> +The 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.
> + value is formed of multi-line text. If its value is ``url``, the
> + 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 1/1] glep-0068: Add notes element for package maintenance instructions
> > 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 , there is one localized "source of truth" for this > documentation, which should remove any ambiguity. > > I would hope that after launching the feature, there would be > a gradual (or sudden?!) shift away from the current comments towards > the tag, maybe even including this in the dev manual. > That makes no sense, since the notes could be version-dependent. -- Andreas K. Hüttel dilfri...@gentoo.org Gentoo Linux developer (council, toolchain, base-system, perl, libreoffice) signature.asc Description: This is a digitally signed message part.
Re: [gentoo-dev] [PATCH 1/1] glep-0068: Add notes element for package maintenance instructions
On Tue, Oct 5, 2021 at 3:10 PM Mike Gilbert wrote: > > On Tue, Oct 5, 2021 at 2:27 PM Sam James wrote: > > > > This adds a new '' 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 , there is one localized "source of truth" for this documentation, which should remove any ambiguity. I would hope that after launching the feature, there would be a gradual (or sudden?!) shift away from the current comments towards the tag, maybe even including this in the dev manual.
Re: [gentoo-dev] [PATCH 1/1] glep-0068: Add notes element for package maintenance instructions
On Tue, Oct 5, 2021 at 2:27 PM Sam James wrote: > > This adds a new '' 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.
