Re: [gentoo-dev] [PATCH 0/1] [RFC] greadme.eclass

[Florian Schmaus <flow@gentoo.org>]

[-- Attachment #1.1.1: Type: text/plain, Size: 3563 bytes --]

On 10/01/2024 12.04, Sam James wrote:
> 
> Florian Schmaus <flow@gentoo.org> writes:
> 
>> I really like the functionality of readme.gentoo-r1.eclass, as it
>> allows to communicate Gentoo-specific information about a package to
>> the user. Especially as it improves the signal-to-noise ratio of
>> messages arriving to our users.
>>
>> However, readme.gentoo-r1.eclass will only show this information on
>> new installs, but not if the information changed. This is a major
>> drawback. Furthermore, readme.gentoo-r1.eclass does not provide an API
>> to assemble the information via heredoc.
>>
>> The following patch includes a new eclass named "greadme", that
>> addresses those shortcomings of readme.gentoo-r1.eclass and hopefully
>> can be seen as a general overhaul.
> 
> I have a few concerns at the moment, but of varying severity:

> 1) The name seems odd (why not readme.gentoo-r2)? > 2) Why can't the existing eclass be improved?

Both points, the name of the eclass and the question if this should be 
added to the existing eclass or as a new eclass, are absolutely *no* 
hill I want to die on.

What I *really* care about is having the functionality that there is a 
readme eclass that *also* shows the elog message if the README's content 
changed (and not just on the first installation of the package).


 > 4) The compression deal seems not worth bothering with.

Just to clarify: you are agreeing that excluding the readme doc from 
being compressed is fine?


> 3) Is the reason for 2) strong enough to introduce a new eclass?
> I don't really want to see a bifurcation in our README eclasses
> if we can help it. Porting to something new takes ages and it's
> a lot of churn.

I think the arguments for introducing a new eclass are strong enough. I 
will elaborate on this in the appendix of this mail, since I don't think 
its what we should focus on at the moment.

However, right now I want clarify that using "docompress -x" in this 
case is agreeable by everyone.

- Flow


# Appendix: Arguments for introducing a new class

readme.gentoo-r1 can be viewed at

https://github.com/gentoo/gentoo/blob/master/eclass/readme.gentoo-r1.eclass

while the simple and short version (203 lines including comments!) of 
the proposed greadme.eclass can be seen at

https://github.com/Flowdalic/gentoo/blob/greadme.eclass-simple/eclass/greadme.eclass

The proposed API of the greadme eclass is already different from 
readme.gentoo-r1. It exports phase functions, which readme.gentoo-r1 
does not. The readme.gentoo-r1 eclass always shoves the full content of 
the readme into an environment variable. Excluding the readme file from 
compression means we do not have to do that in greadme.

Please feel invited take a look at the code of both eclasses and make 
yourself an opinion if it is sensible to incorporate greadme.eclass into 
the existing eclass.

Then maybe also also look a the API of both eclasses. Switching from 
readme.gentoo-r1 to greadme is simple and straightforward in most cases.

Furthermore, the name readme.gentoo-r1 seems odd, it is one of the few 
eclasses that use a dot as separator (although, I can see why this may 
been done). Looking at eclasses/ it appears that readme-gentoo-r1.eclass 
would be more in-line with the existing eclasses. Or, as a matter of 
opinion, maybe better, because shorter: greadme

Adding a new readme eclass hopefully is not a bifurcation, cause we 
ideally would be able to phase out readme.gentoo-r1.




[-- Attachment #1.1.2: OpenPGP public key --]
[-- Type: application/pgp-keys, Size: 17273 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 618 bytes --]