Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)
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 OpenPGP_signature Description: OpenPGP digital signature
Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)
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 signature.asc Description: PGP signature
Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)
> 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 signature.asc Description: PGP signature
Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)
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
Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)
> On Wed, 06 Oct 2021, Alec Warner wrote: > On Tue, Oct 5, 2021 at 10:37 PM Ulrich Mueller 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 signature.asc Description: PGP signature
Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)
On Tue, Oct 5, 2021 at 10:37 PM Ulrich Mueller 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
Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)
> 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 signature.asc Description: PGP signature
Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)
> 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 signature.asc Description: PGP signature
Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)
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 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 ku...@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
Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)
On Tue, Oct 5, 2021 at 1:36 PM Sam James wrote: > > > > > On 5 Oct 2021, at 21:29, Alec Warner 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 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 > >> > >> > > >
Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)
> On 5 Oct 2021, at 21:29, Alec Warner 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 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 >> >> > signature.asc Description: Message signed with OpenPGP
Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)
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 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 > >
Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)
> 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 >
Re: [gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)
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
[gentoo-dev] [PATCH 0/1] Add 'notes' element to metadata.xml (GLEP 68)
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
