This bug tracks the implementation of the EAPI 3 feature mentioned in the summary.
From PMS: 12.1.2 REPLACING_VERSIONS and REPLACED_BY_VERSION In EAPIs listed in table 12.2 as supporting it, the REPLACING_VERSIONS variable shall be defined in pkg_preinst and pkg_postinst. In addition, it may be defined in pkg_pretend and pkg_setup, although ebuild authors should take care to handle binary package creation and installation correctly when using it in these phases. REPLACING_VERSIONS is a list, not a single optional value, to handle pathological cases such as installing foo-2:2 to replace foo-2:1 and foo-3:2. In EAPIs listed in table 12.2 as supporting it, the REPLACED_BY variable shall be defined in pkg_prerm and pkg_postrm. It shall contain at most one value.
This is in git now: http://git.overlays.gentoo.org/gitweb/?p=proj/portage.git;a=commit;h=2339fbb2fc4f54161787afebb768d60afc3511ba
*** Bug 48920 has been marked as a duplicate of this bug. ***