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.