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

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

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

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

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

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

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



<div dir="auto"><br><div class="gmail_quote" dir="auto"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Maybe we could just add README files to the package directories<br>
in question.  This would have the clear advantage that the files will be<br> immediately visible.<br></blockquote></div><div dir="auto"><br></div><div dir="auto">I&#39;ll personally prefer a readme.</div><div dir="auto">Also almost all metadata.xml features are underused</div><div class="gmail_quote" dir="auto"><blockquote class="
gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
</blockquote></div></div>

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

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

-----BEGIN PGP SIGNATURE-----

iQGTBAEBCgB9FiEEYOpPv/uDUzOcqtTy9JIoEO6gSDsFAmFct1lfFIAAAAAALgAo aXNzdWVyLWZwckBub3RhdGlvbnMub3BlbnBncC5maWZ0aGhvcnNlbWFuLm5ldDYw RUE0RkJGRkI4MzUzMzM5Q0FBRDRGMkY0OTIyODEwRUVBMDQ4M0IACgkQ9JIoEO6g SDsRMQf8CAmvc5a+wN53hluLNilJEtqsCe8vGhFsDUPyHheZDoZ18mbQD8d8xqmh 7lRRKXtpSxOYSURUr4Ol3zMkt4kPFZh2R6yc2GHFYhwr/jJSJdjhLN+e88h4dd8V w/z+OzgI9V6amQ9uTbtrMkbq1HG7804jAm/Aoj3i04cve/sOdOB1iCRi/eayRz79 qQ0GkJv/ZgVJMWI5U9NsekjBAq2gR3yXH/y4r4aVGF/Pt6zqtV6xQ7BiTswNVR5p 4SG7iOmk1DUU0bC78utDrSGb/Dw9EfALG2PgJHLHi5ljfaBgQXz6UHKKYoCEKUZk alycFkZ50O+ea51a6vyDWRSWwtKOVg==
=m01f
-----END PGP SIGNATURE-----

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

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

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

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

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

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

-----BEGIN PGP SIGNATURE-----

iQFDBAEBCAAtFiEEtDnZ1O9xIP68rzDbUYgzUIhBXi4FAmFdNhgPHHVsbUBnZW50 b28ub3JnAAoJEFGIM1CIQV4uCNUIALgJAsODll8P4KfeXPi8VM/SeXL3DAl+FgTW qQSE/q/wxwKRrkx/JFZPY8y2BB2lZh/ArqM3inzBFu67huQKEjnz3v9pedVexmSn 2+A6VhT1HFnh428wj9shhYZV1oLKKPV5bynZfR/3dyIJKjHsyVl94PHfmSX4Dq56 dY5f2zIOKED0JRIZxQat72Z90opKYEZr3ub6yCEgB+asYBJdIFBuYKC14+zyx+9m xLvm+OpyEUUKySKkvy+9hHoMN59zJkt8u1lgHg0NwzzuDewxG1SDGxNautMLB2Mh /VYIE7iT7ZLTZzBD+IyyKtnBBC6bYJUzlJwiu3kEFMngwfSkmG8=
=nwaM
-----END PGP SIGNATURE-----

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

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

--=-=-Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQFDBAEBCAAtFiEEtDnZ1O9xIP68rzDbUYgzUIhBXi4FAmFdNAUPHHVsbUBnZW50 b28ub3JnAAoJEFGIM1CIQV4uEbcH/0KoutBiJzWW661ddqsXMu7pM1OprcrWvMnG i86yI8Qy4qUFhdRSEe5LGOyLFMiS8dEhZkEwxNTEKKsS8jv3yYYiY9dRPsvZddqt hGeav1AcbQtFdLhsIPSuzjO3s2k2BtIEFpY46EFPlpTM+Sn0yI6ZIUgLvem8f0Ru RNSCcp0hgOgXm1cDaQrhhpoj0Th6f54USBZZqpMOMqMVeFk1k6zqM99kw0MmyiWs bAz+Z7WOzAVHYuy/LTTaMvUcYSePXzjy6D1gbBYjaEgi0PpaNGa/LNKwHTi697aF O20rKLf19Hb5TKyXN0nuLheWc6pfwuAPmrYJQVWEgoRWFeIbvq8=Ynw0
-----END PGP SIGNATURE-----

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

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

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

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

-----BEGIN PGP SIGNATURE-----

iQFDBAEBCAAtFiEEtDnZ1O9xIP68rzDbUYgzUIhBXi4FAmFdbWEPHHVsbUBnZW50 b28ub3JnAAoJEFGIM1CIQV4uRwsIAMYBv9y0JvF40nWjHS1ulReDNRrk6L9K119k t97dDpn59bRliiNxs2kOFjfYAVQgB91DOT5snox0qCTuWgodG/wfO4CEafPxTcz2 rAjPg9m5FlT4E+ueig/A1AmQhHrWUHeymh/u3vTr7XEMR2+2oO2NJYys2xa2TnE6 obUbmzz7atdIRnKp1obZvsqP9k6RbOsL8Uqb/f6XNaSOPfR4qJC+DpJa+dZ23IcL 8usMZaooIEO0IpU47VVcjKXjxyJQIuwz7jE12pHFNznB9WNu/bif+0SUcZtRCuLi RWaD73Rr73M0JFKkog07ysrJusMuoTZLMUsdGa176WDZPMgQQ34=
=Px2+
-----END PGP SIGNATURE-----

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

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

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

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

--=-=-Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQFDBAEBCAAtFiEEtDnZ1O9xIP68rzDbUYgzUIhBXi4FAmFeoXUPHHVsbUBnZW50 b28ub3JnAAoJEFGIM1CIQV4ueKgIAJLOue/9hOmb3TS25bNlM8P7q+pVVIA+D+xs 55VL2aD00M2mEHZVRt1yNEvjqxTzxCaQS1Rj4Tq99Ki79tmoWEaXLlEVRCMRysLe MVX5uR2psX+Q4U1lw9PwXodCq9YtxcXTZo9BYseDqavejH3SMGYjZBZ12gkgvWca 6B8QvBdJJR/rIj90x8kTriBrrwMXjmmaSmmgR5mBOCpBRh4JaH1nrtWjutMg5fmK Jn83tvsmFK8jf/awVpw3j6vtB9/XKP2qS8vYKoFn6IzF+v2Zzr66uJEFa60CBYuI R+ZzsecnDzWE28cOjiNawo3F7d9A7WJGEvkpkGGmmKARwRHbm/Q=Kguo
-----END PGP SIGNATURE-----

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

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

-----BEGIN PGP SIGNATURE-----

iQEzBAABCAAdFiEEx3SLh1HBoPy/yLVYskQGsLCsQzQFAmIhXsIACgkQskQGsLCs QzR7mwf/fnFCcA+/PBVLeD2k0o9HC92ABQbCA2vTBtCaPhBJYv6MhBvKq4DbVHVg GmWgh76xt72de4gpFIH7Ho3tlSIpfz+FBclkYgFkXDKIVgbd1EzcF5ae2S/VK2xB frTBTgMgYNBO27qlBl6GVqiduev7DSRYxmshYzocLBYATe8hgDXLBiGJbF58x8Ra Mo2PYvkTQ+ANmZ1YqJ1SdXbGAdTb1imZqsWU/Hvvi9e71fmfk8tSsAN7Q4p+Z1L/ JTUAMBUnhwzTx0yA+R2oJP0F8arDfO1/Yv792dijIkdxdaDwV09z6vdAc9gE5GKr Znvps6F/qsH4Vlsb0dul95piQFoNqQ==
=xUpf
-----END PGP SIGNATURE-----

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

This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --------------pevIQR9IZ5aLyhW0aDyAqnN5
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

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

--------------pevIQR9IZ5aLyhW0aDyAqnN5--

-----BEGIN PGP SIGNATURE-----

iQGTBAEBCgB9FiEEltRJ9L6XRmDQCngHc4OUK43AaWIFAmIhx7JfFIAAAAAALgAo aXNzdWVyLWZwckBub3RhdGlvbnMub3BlbnBncC5maWZ0aGhvcnNlbWFuLm5ldDk2 RDQ0OUY0QkU5NzQ2NjBEMDBBNzgwNzczODM5NDJCOERDMDY5NjIACgkQc4OUK43A aWKtjwf+Ks0R4qXbKx6lbRqD6rxG0AApAOXt5DN8+zJs/sMu5rRVorgF5IawwNp4 rOiwqP0V8IaFNiWWmaKiQUFdn+kbEp784/5eCwS+5PoHcNlfHMNOn+PxUZvy334Y BmYOM5/WoqCC4oVjETNS/Kh7a7e2w0LyFHlL0cX0LlnRUlBEhmtQoYXGRJa71T3a DMAqfL0BtEg/jJA+HAPp4wZwM/jsCrXr5gE19vA53xyZ17Z4IGCejx3/YSg8PqXY WbXykuRWZiB1XsnK5HeCBNJabkrjRNLJBqT83LQLN9erNkkfyHiKPq0BWYeiAWH9 O+SGXxfntFdXDnOcNKL0ItWp4H09bQ==
=7vUf
-----END PGP SIGNATURE-----

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