Bug 669848 – Ebuild writing style guide GLEP is needed

• Product: Documentation
• Status: RESOLVED NEEDINFO

[Description Eugene Bright 2018-10-28 11:53:54 UTC]

Currently maintainers are prone to prohibit any ebuild formatting changes.
Eclass inheritance and IUSE definition are done in one line by convention.
I personally stand against using long lines in ebuilds. PEP8 should be a good point to start new GLEP.

My points in defence of multi-line IUSE:
 - more readable
 - easy flag sorting (vim's ":!sort" is enough)
 - clear `git diff` in case of flag addition/deletion

The same is applicable for inheriting eclasses if only one class is inherited per line.

Link to the precedent.
https://github.com/gentoo/gentoo/pull/10192#discussion_r227992990

Reproducible: Always

Steps to Reproduce:
1. Send a new ebuild formatted in PEP8 manner
Actual Results:  
Ebuild is not accepted by maintainer.

Expected Results:  
Ebuild is accepted by maintainer.

[Comment 1 Ulrich Müller 2018-10-28 17:14:20 UTC]

<GLEP editor>
We don't assign GLEP numbers unless there is a first draft. So please follow the workflow as outlined in GLEP 1:
https://www.gentoo.org/glep/glep-0001.html#glep-work-flow
</GLEP editor>

(Also, the devmanual already addresses line length and whitespace. I doubt that a separate GLEP would be the best format a style guide.)

[Comment 2 Eugene Bright 2018-10-28 17:26:27 UTC]

Devmanual should be enough. I just can't find related style guides in it.
Could you give me a hint?

[Comment 3 Ulrich Müller 2018-10-28 17:54:29 UTC]

https://devmanual.gentoo.org/ebuild-writing/file-format/index.html#indenting-and-whitespace

There are also some tacit conventions, like having single lines for things like KEYWORDS, IUSE, and inherit, in order to facilitate grep across the tree. I don't think we've any formal writeup for those, but everyone seems to follow them.

[Comment 4 Eugene Bright 2018-10-29 08:59:58 UTC]

Thank you very much.
Relying on grep doesn't look a good justification for prohibiting multi-line IUSE. The assumption that IUSE is defined in one line is generally wrong. Moreover writing long lines contradicts with manual recommendations as it's really *possible* to make them readable and short.
Why not to use specialized tools like equery for probing for USE flags?

[Comment 5 Ulrich Müller 2018-10-29 10:52:15 UTC]

As I said, this is currently not an item for the GLEP editors, but should be discussed on the mailing lists.

(My personal opinion is that there will be zero chance for changing that long established convention. Feel free to try, though.)

$ find /var/db/repos/gentoo -name '*.ebuild' -exec grep '^KEYWORDS=".*"' '{}' + | wc -l
31840
$ find /var/db/repos/gentoo -name '*.ebuild' -exec grep '^KEYWORDS="[^"]*$' '{}' + | wc -l
1