| 1 |
On Tue, Oct 5, 2021 at 3:10 PM Mike Gilbert <floppym@g.o> wrote: |
| 2 |
> |
| 3 |
> On Tue, Oct 5, 2021 at 2:27 PM Sam James <sam@g.o> wrote: |
| 4 |
> > |
| 5 |
> > This adds a new '<notes/>' element to allow maintainers to describe |
| 6 |
> > package-specific quirks or other instructions on how to correctly |
| 7 |
> > maintain a package. This is intended to encourage developers to document |
| 8 |
> > knowledge and increase the bus-factor of packages which are delicate |
| 9 |
> > but must live beyond a maintainer. |
| 10 |
> |
| 11 |
> Personally, I am much more likely to notice a comment at the top of |
| 12 |
> the ebuild than a new element in metadata.xml. |
| 13 |
|
| 14 |
I generally agree that comments are more visible/noticeable than |
| 15 |
metadata, however, I also think that this could be a good step forward |
| 16 |
for overall maintainability. The issue with documenting these things |
| 17 |
in comments is that the comment lives only within the specific version |
| 18 |
of the ebuild in which it is authored: it is up to the maintainer to |
| 19 |
carry those comments over when version bumping. While this is |
| 20 |
generally not a problem due to copy/paste, I think it is messy - there |
| 21 |
could be an update to the comment from one version to the next, |
| 22 |
meaning I now have two version of the comment floating around. |
| 23 |
|
| 24 |
With <note/>, there is one localized "source of truth" for this |
| 25 |
documentation, which should remove any ambiguity. |
| 26 |
|
| 27 |
I would hope that after launching the <note/> feature, there would be |
| 28 |
a gradual (or sudden?!) shift away from the current comments towards |
| 29 |
the <note/> tag, maybe even including this in the dev manual. |
Archives