On 10/01/2024 12.04, Sam James wrote: > > Florian Schmaus 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.