New EAPI specification
This page explains the need for a new EAPI specification and the guidelines for it.
The ebuild format is currently covered by the Package Manager Specification. This is an Exherbo-originated project that is maintained in Gentoo-Exherbo cooperation. Sadly, the current spec shows a number of issues.
Most notably, the current organization and wording often proves cumbersome for developers. It is easy to mis-understand some of the sections of the specification. Sometimes it is necessary to read multiple (non-cross-referenced) sections to understand the actual status.
The specification often misses rationale, historical or implementation notes. It also has been changed retroactively a few times without a proper behavior change note.
The specification offers only limited description of ebuild, profile and repository format. It lacks any details on multi-repository systems, installed package database (vardb), md5-cache. The Manifest files are specified only via reference to GLEP-44 which also doesn't cover most recent changes in Manifest format.
Guidelines for new specification
The new EAPI specification needs to follow the following guidelines:
- it should be self-contained and provide coverage of all the most important interoperability aspects.
- It should be focused on the newest EAPI. Previous EAPIs should be covered as differences from the newest EAPI and dedicated historical sections.
- It should contain (as appropriately marked subsections) rationales, implementation notes, explanatory notes, possibly examples.
- Format descriptions should be as simple as possible. Whenever appropriate, a BNF variant should be preferred over textual descriptions or regular expressions.