On Tue, Oct 5, 2021 at 3:10 PM Mike Gilbert <flop...@gentoo.org> wrote: > > On Tue, Oct 5, 2021 at 2:27 PM Sam James <s...@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.
