Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!
Bug 186454 - [Future EAPI] Remove DESCRIPTION and HOMEPAGE from ebuilds and move it to metadata.xml
Summary: [Future EAPI] Remove DESCRIPTION and HOMEPAGE from ebuilds and move it to met...
Status: RESOLVED WONTFIX
Alias: None
Product: Gentoo Hosted Projects
Classification: Unclassified
Component: PMS/EAPI (show other bugs)
Hardware: All Linux
: Normal normal (vote)
Assignee: PMS/EAPI
URL:
Whiteboard:
Keywords:
: 519626 (view as bug list)
Depends on:
Blocks: future-eapi
  Show dependency tree
 
Reported: 2007-07-24 12:04 UTC by Petteri Räty (RETIRED)
Modified: 2019-12-04 23:30 UTC (History)
8 users (show)

See Also:
Package list:
Runtime testing required: ---


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Petteri Räty (RETIRED) gentoo-dev 2007-07-24 12:04:19 UTC
http://article.gmane.org/gmane.linux.gentoo.devel/50905
Comment 1 Michał Górny archtester Gentoo Infrastructure gentoo-dev Security 2013-08-30 10:59:15 UTC
Any progress here? We could supposedly try getting it done for EAPI 6 but I'm not sure if finding and cleaning up all uses of DESCRIPTION would be worth it. We need to consider external tools, eix specifically.
Comment 2 Ulrich Müller gentoo-dev 2014-07-07 16:53:33 UTC
No progress, therefore closing.
Comment 3 Ulrich Müller gentoo-dev 2014-08-12 07:54:35 UTC
*** Bug 519626 has been marked as a duplicate of this bug. ***
Comment 4 Anthony Ryan 2014-08-12 22:51:40 UTC
I would like to revisit this issue and I'm willing to write the necessary patches for portage/repoman if there's developer interest to merge them and update the specification. I believe we should move HOMEPAGE and DESCRIPTION into metadata.xml (a more complete description of my motives can be found in #519626).

Making this change should result in more accurate metadata for packages, it may encourage wider use of <bugs-to>, <doc> & <changelog>. And it can be introduced in a way that users won't be affected and ebuild developers will have a clear migration path.
Comment 5 Ulrich Müller gentoo-dev 2014-08-13 00:02:18 UTC
For reference, previous mailing list discussions of the issue:
http://thread.gmane.org/gmane.linux.gentoo.devel/50903/focus=50905
http://thread.gmane.org/gmane.linux.gentoo.devel/58924

Specifically:
- DESCRIPTION is mandatory in existing EAPIs, so removing it from ebuilds
  would require an EAPI bump.
- Both variables can change between SLOTs (see media-libs/jpeg or
  x11-libs/motif for examples); HOMEPAGE can change between versions (e.g. if
  upstream maintainer changes).
- HOMEPAGE must be accessible as a variable from within ebuilds (e.g. in
  src_nofetch() if fetch restricted). For this, portage would need to parse
  XML which is time consuming and may require additional dependencies.
- Both variables are saved in the metadata cache, in the VDB, and in xpak,
  such that the information is available for installed packages, as well as
  for binary packages.
- It is very convenient to have these in the ebuild for user submitted
  packages.
- Both DESCRIPTION and HOMEPAGE can be set via an eclass. By a previous scan,
  some 15 or 20 % of ebuilds in the tree make use of this.
Comment 6 Anthony Ryan 2014-08-13 15:07:05 UTC
To address each of your concerns individually:

- DESCRIPTION is mandatory in existing EAPIs, so removing it from ebuilds
  would require an EAPI bump.

That seems fine, EAPI 6 is being worked on right now, and that gives us plenty of time to prepare for this change.


- Both variables can change between SLOTs (see media-libs/jpeg or
  x11-libs/motif for examples); HOMEPAGE can change between versions (e.g. if
  upstream maintainer changes).

I hadn't considered maintainer changes, but in my opinion that's still fairly easy to do, the latest maintainer homepages could be set as usual, and legacy homepages could be specified with a slot attribute.

<upstream>
    <homepage>http://sourceforge.net/projects/motif/</homepage>
    <!-- previous maintainer homepage -->
    <homepage slot="2.2">http://motif.ics.com/</homepage>
</upstream>

- HOMEPAGE must be accessible as a variable from within ebuilds (e.g. in
  src_nofetch() if fetch restricted). For this, portage would need to parse
  XML which is time consuming and may require additional dependencies.

I would argue in the case of fetch restricted packages, they could still use this pattern, but with a different variable name (which is a minor inconvenience for ebuild authors). Using something like FETCH_URI instead would allow links to Download pages. A number of ebuilds already do something along these lines with their own variables (dev-java/oracle-jre-bin having JRE_URI for example), and this would simply standardize it. Some packages may still have an identical HOMEPAGE and FETCH_URI.

- Both variables are saved in the metadata cache, in the VDB, and in xpak,
  such that the information is available for installed packages, as well as
  for binary packages.

If we we are concerned about the loss of this information in /var/db/pkg we could simply place a copy of metadata.xml (at the time of installation) into package directories).

- It is very convenient to have these in the ebuild for user submitted
  packages.

I understand this, but for new ebulid submissions the process would simply change that people submit a metadata.xml file together with an ebuild, which should save developers additional effort as the metadata.xml file needs to be created for each package anyways. Similarly, by drawing extra attention to the metadata.xml file, other upstream attributes like <bugs-to> and <docs> could be filled out to help improve the accessibility of this information (in case portage QA warnings ever decide to link directly to upstream bug trackers).

- Both DESCRIPTION and HOMEPAGE can be set via an eclass. By a previous scan,
  some 15 or 20 % of ebuilds in the tree make use of this.

It's true that this is happening, but it's also encouraging some strange patterns in eclasses. The mysql-multilib eclass has the following:

DESCRIPTION="A fast, multi-threaded, multi-user SQL database server"
HOMEPAGE="http://www.mysql.com/"
if [[ ${PN} == "mariadb" ]]; then
        HOMEPAGE="http://mariadb.org/"
        DESCRIPTION="An enhanced, drop-in replacement for MySQL"
fi
if [[ ${PN} == "mariadb-galera" ]]; then
        HOMEPAGE="http://mariadb.org/"
        DESCRIPTION="An enhanced, drop-in replacement for MySQL with Galera Replication"
fi
if [[ ${PN} == "percona-server" ]]; then
        HOMEPAGE="http://www.percona.com/software/percona-server"
        DESCRIPTION="An enhanced, drop-in replacement for MySQL from the Percona team"
fi


With all of those issues, the entire migration can be done in a few simple steps:
1. Write an script to parse all ebuilds recursively in a directory, interpret and fill out metadata.xml using the rules we settle on.
2. Write a second script, that would determine if HOMEPAGE is used in pkg_norestrict (or anywhere else), and remove/rename or warn the developer accordingly. And remove DESCRIPTION unconditionally.
3. Update eclasses that set DESCRIPTION and HOMEPAGE so they only set it if EAPI < 6.
4. portage/repoman updates.

I'm willing to do all of this if the development team is willing to use my work to make this transition a reality for EAPI 6.
Comment 7 Michał Górny archtester Gentoo Infrastructure gentoo-dev Security 2014-08-13 17:43:49 UTC
(In reply to Anthony Ryan from comment #6)
> To address each of your concerns individually:
> 
> - DESCRIPTION is mandatory in existing EAPIs, so removing it from ebuilds
>   would require an EAPI bump.
> 
> That seems fine, EAPI 6 is being worked on right now, and that gives us
> plenty of time to prepare for this change.

Please don't expect this to end up in EAPI 6. This is highly controversial and will require proper debate, and is not really urgent enough.

> - Both variables can change between SLOTs (see media-libs/jpeg or
>   x11-libs/motif for examples); HOMEPAGE can change between versions (e.g. if
>   upstream maintainer changes).
> 
> I hadn't considered maintainer changes, but in my opinion that's still
> fairly easy to do, the latest maintainer homepages could be set as usual,
> and legacy homepages could be specified with a slot attribute.
> 
> <upstream>
>     <homepage>http://sourceforge.net/projects/motif/</homepage>
>     <!-- previous maintainer homepage -->
>     <homepage slot="2.2">http://motif.ics.com/</homepage>
> </upstream>

Please note that there's existing restrict="" attribute that could serve the purpose.
Comment 8 Anthony Ryan 2014-08-13 18:22:41 UTC
Indeed there is. That actually works perfectly for this, it seems I had skimmed over it in the documentation.
Comment 9 Ulrich Müller gentoo-dev 2018-08-08 14:13:19 UTC
No progress since 4 years. Closing (again).
Comment 10 Ulrich Müller gentoo-dev 2019-11-13 14:33:17 UTC
(In reply to Ulrich Müller from comment #5)
> For reference, previous mailing list discussions of the issue:
> http://thread.gmane.org/gmane.linux.gentoo.devel/50903/focus=50905
> http://thread.gmane.org/gmane.linux.gentoo.devel/58924

Since this keeps coming up, here are updated references to the old discussions:

Marijn Schouten. "Re: RFC: Forbid using versions in DESCRIPTION".
gentoo-dev mailing list, 2007-07-24, Message-ID 46A5E634.3030903@gentoo.org,
https://archives.gentoo.org/gentoo-dev/message/9e5271df475cf74e6581d3999d82889f

Diego Pettenò. "[RFC] Moving HOMEPAGE out of ebuilds for the future".
gentoo-dev mailing list, 2008-11-30, Message-ID m21vwtl53v.fsf@gmail.com,
https://archives.gentoo.org/gentoo-dev/message/b6eae4be12fccd2274a27c00383ee08b