Project:Package Manager Specification/Future EAPI process

Requirements for a future EAPI proposal

For a change to be included in a future EAPI, the four following tasks need to be done (in any order):

1. A future EAPI bug needs to be open for the change, assigned to “Gentoo Hosted Projects” / “PMS/EAPI”. The bug should contain a short summary of the change. It will be used to track the progress and feedback on the change until it is eventually included.
2. An exact specification for the PMS (git format-patch format strongly preferred) needs to be prepared and approved. The PMS team will review the patch for factual correctness, clarity and consistency with the document style. The team may also have useful remarks regarding the idea but it will not reject it even if they disagree with the idea.
3. A reference implementation for Portage needs to be prepared and approved. The Portage team will review it for inclusion.
4. The change needs to be discussed on the gentoo-dev mailing list. For simple changes, the discussion as part of the eventual Council agenda item for the next EAPI may be enough. However, for more complex or controversial changes, starting a dedicated thread early is recommended.

Some of the teams or developers may offer to do some of the above steps for your idea. However, they are not required to do so. Furthermore, a promise that a team will do the work is not equivalent to it actually being done.

Please note that while a change might be tentatively included in the next EAPI proposal before all of the above steps are complete, the Council can remove it afterwards if the implementation is getting delayed or it is complex/controversial and did not receive enough time for discussion and/or testing.

Alternatively, new features may be proposed via a GLEP. This needs to follow the usual GLEP process and remains unaffected by this policy.

Direction for the PMS/EAPI

While the EAPI process is pretty open for ideas, it is a good idea to try to maintain a single direction in the PMS and try to follow existing standards whenever possible.

The current direction is to add new functions and features that either:

1. are commonly used in ebuilds (or can be used to replace existing common use),
2. rely on package manager internals, configuration, etc. and therefore can not be reliably implemented in eclass,
3. can avoid a class of common mistakes in ebuilds.

At the same time, the additions have to:

• either be generic or be suitable for a generic implementation,
• not be specific to a special subset of packages that already have a well-defined eclass — e.g. a function used only for CMake build system is better off in cmake.eclass,
• be pretty stable and not require frequent changes,
• not be equivalent to a trivial one-liner — better use the one-liner directly,
• be suitable for clear description in words or an algorithm without adding too much complexity.

Forming a new EAPI

Normally the future EAPI proposals are reviewed and discussed continuously. Periodically the PMS team reviews all the open future EAPI bugs and considers the progress of updating them. When the ideas are mature enough, they are marked feasible-for-next-eapi.

The process of forming a new EAPI is usually started by the PMS team when the previous EAPI is well deployed and there is a significant number of feasible proposals. However, a new EAPI may also be created for a single proposal if it is deemed important enough.

When starting to work on the next EAPI, PMS team does the following:

• They start collecting items for a tentative next EAPI feature list (e.g. Future_EAPI/EAPI_7_tentative_features) from the proposals marked as feasible.
• They prepare a branch dedicated to the next EAPI in PMS and updates tables and other boilerplate for the next EAPI.
• They start pushing work forward. This includes working on some of the feasible proposals directly or encouraging the submitters to work on them.
• They announce the initial timeline for preparing the next EAPI, encouraging discussion on the ideas collected so far and submission of more ideas in time.

When the tentative list is fairly complete and unlikely to change much, the PMS team puts it on the Council agenda for pre-approval. This provides the opportunity for additional feedback while the features are still under work.

As the specification patches are completed, they are merged into the branch dedicated to the next EAPI. When the updated specification is ready and all the included proposals have good chances of completion, the PMS team pushes the final version to the Council.