| 1 |
On 10/5/21 12:09, Michał Górny wrote: |
| 2 |
> On Tue, 2021-10-05 at 19:27 +0100, Sam James wrote: |
| 3 |
>> This is a preliminary version/draft of a proposed change to |
| 4 |
>> GLEP 68. |
| 5 |
>> |
| 6 |
>> I'd like to introduce a method for developers to signal anything |
| 7 |
>> special about a package and how to correctly maintain it. |
| 8 |
>> |
| 9 |
>> Sam James (1): |
| 10 |
>> glep-0068: Add notes element for package maintenance instructions |
| 11 |
>> |
| 12 |
>> glep-0068.rst | 26 +++++++++++++++++++++++--- |
| 13 |
>> 1 file changed, 23 insertions(+), 3 deletions(-) |
| 14 |
>> |
| 15 |
> To be honest, I don't think adding it to metadata.xml is a good idea. |
| 16 |
> This is not something that's going to be machine-parseable, |
| 17 |
> and expecting people to look into metadata.xml to see if it's even |
| 18 |
> present is a bit much. |
| 19 |
> |
| 20 |
> Maybe we could just add README files to the package directories |
| 21 |
> in question. This would have the clear advantage that the files will be |
| 22 |
> immediately visible. |
| 23 |
> |
| 24 |
Some of the devs use their username or project pages on the wiki for |
| 25 |
maintainers notes. That's a decent place to keep them since there is not |
| 26 |
an in-source place, but truly the closer the documentation can be kept |
| 27 |
to the source the better. |
| 28 |
|
| 29 |
I also like the idea of markdown files or RST files living in gentoo::. |
| 30 |
I personally find RST to be a bit more challenging to write, but it's |
| 31 |
simple enough to learn and we 'already have RST to HTML conversion on |
| 32 |
www.g.o for GLEPs. GitHub will render either file format in browser. Not |
| 33 |
sure about all the other Git* sites. |
| 34 |
|
| 35 |
Apparently the MD and RST formats are somewhat interchangeable if one |
| 36 |
does not go too crazy on formatting: |
| 37 |
https://gist.github.com/javiertejero/4585196 |
Archives