Bug 612630 – New policy: ebuild code must be contained within .ebuild and .eclass files

• Product: Gentoo Linux
• Status: RESOLVED FIXED

[Description Michał Górny 2017-03-14 15:43:05 UTC]

Following the recent events, I would like to request a vote upon an explicit policy disallowing splitting ebuild code between multiple non-standard files. I would suggest a wording alike:

==
The ebuild code must be wholly contained within the .ebuild and .eclass files, as defined by the PMS. It is explicitly forbidden to split the ebuild code into external files that are loaded via source, eval or any other possible method.
==


The rationale:

a. We should aim for high maintainability of ebuilds, and therefore avoid needless complexity or surprise. Outsourcing ebuild code to non-standard locations is against the principle of least surprise, introduces unnecessary complexity and makes the ebuilds harder to maintain for others. This effectively discourages others from contributing and results in a high bus factor which is certainly undesirable for core system packages.

b. The non-obvious code locations are usually not accounted for in various tools and developer practices. For example, the common attempts of grepping ebuilds and eclasses for function calls will not catch the calls occurring within external files.

c. Some of the repoman checks are applied to .ebuild files only. By moving the code out of ebuilds to non-standard files, the checks do not catch issues correctly. While this is currently true of eclasses as well, this issue can be solved to some degree, whereas we can't reliably make repoman find and scan any ebuild code in FILESDIR and other locations.


It should be noted that:

a. This policy does not collide conceptually with a potential future EAPI extension providing per-ebuild eclasses. The point is, however, that such an extension should be well-defined in the PMS.

b. The non-standard code locations are only used by a few packages (3, if I recall right) and provide no specific advantages over the standard locations (ebuilds and eclasses).


Please discuss/vote.

[Comment 1 Ulrich Müller 2017-03-14 17:20:33 UTC]

Would this policy apply to new ebuilds only, or also to existing ones?

[Comment 2 Michał Górny 2017-03-14 17:41:26 UTC]

(In reply to Ulrich Müller from comment #1)
> Would this policy apply to new ebuilds only, or also to existing ones?

Either way works for me. I'd say applies immediately to new ebuilds, and we phase out the existing uses. However, we're doing the latter for other bugs anyway, so I don't think that to be a problem.

[Comment 3 David Seifert 2017-03-14 18:43:05 UTC]

Vote: Yes
Apply to: whole tree, not just new ebuilds

[Comment 4 Ulrich Müller 2017-03-16 19:48:46 UTC]

I vote yes.

[Comment 5 Michał Górny 2017-03-17 19:51:00 UTC]

Let's do this keywording-like. I've CC-ed all members who haven't voted yet. Please vote and remove yourself from CC once done ;-).

[Comment 6 Manuel Rüger (RETIRED) 2017-03-17 20:23:40 UTC]

I'd prefer a rewording 

"The ebuild code must be wholly contained by files that are defined by the PMS, which is as of $date .ebuild and .eclass files."

Saves us from rewording the policy just in case PMS changes and adopts eblits-ng or something else.

Otherwise: Aye.

[Comment 7 Chris Reffett (RETIRED) 2017-03-18 13:32:55 UTC]

Aye, new ebuilds only.

[Comment 8 Mikle Kolyada (RETIRED) 2017-03-18 20:12:17 UTC]

Yes, New ebuilds.

[Comment 9 Amy Liffey 2017-03-18 22:04:11 UTC]

Yes, for new ebuilds.

[Comment 10 Michał Górny 2017-03-18 22:07:45 UTC]

For completeness, my vote: yes, to all.

[Comment 11 Sergey Popov 2017-03-21 08:57:52 UTC]

Yes, for new ebuilds.

[Comment 12 Rick Farina (Zero_Chaos) 2017-03-21 15:26:30 UTC]

Yes, to all, or just moving forward

[Comment 13 Patrick Lauer 2017-03-21 16:25:38 UTC]

Yes.

[Comment 14 William Hubbs 2017-03-23 21:56:08 UTC]

I vote yes to all.

[Comment 15 Michał Górny 2017-03-24 15:33:37 UTC]

I hope Tommy doesn't mind if I call the time out after 10 days and summarize the results without his vote. We have a definitive majority, and his vote would not change the result.

So to summarize:

a. 11 out of 12 QA members voted,

b. The 11 QA members unanimously approved the motion for new ebuilds,

c. 7 out of 11 members approved the motion for existing ebuilds.

This considered, the following policy is now in effect (wording by mrueg):

===
The ebuild code must be wholly contained in files that are defined by the PMS, which as of 2017-03-24 are .ebuild and .eclass files. It is explicitly forbidden to split the ebuild code into additional files that are loaded via source, eval or any other possible method.
===

The policy applies both to new and existing ebuilds. The two known violations are already being fixed today as part of #586422 and #586424.

[Comment 16 Michał Górny 2017-03-24 15:40:44 UTC]

Added to the wiki:

https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Policies#Ebuild_code_must_be_wholly_contained_in_PMS_files

[Comment 17 Michał Górny 2017-03-24 15:50:32 UTC]

...and announcement sent to gentoo-dev-announce@ with cross-post to gentoo-dev@.