[ << ] [ < ] [ Home ] [ > ] [ >> ]

5. Ebuild Maintenance HOWTO

• Introduction
• Adding a new ebuild
• Stabilizing ebuilds
• Stabilization rules
• Upgrading ebuilds
• Moving ebuilds
• Removing ebuilds
• Removing a package
• Conflicting files

5.a. Introduction

This guide aims to explain common everyday ebuild maintenance routines, as well as other rarer maintenance routines which developers may not be familiar with.

5.b. Adding a new ebuild

When adding a new ebuild, you should only include KEYWORDS for architectures on which you have actually tested the ebuild, confirming that it works as it should and that USE flags are properly honoured in the resulting package which would be installed. If possible, you should give the actual library or application thorough testing as well, since you would be responsible for any breakages for your architecture(s). Minimal testing such as checking that the application starts up without any errors should always be performed.

If you are adding a user-submitted ebuild, do not assume that the submitter has done testing on various architectures: often, KEYWORDS are cloned across packages or generated from documentation in the source packages, which does not signify that the package does indeed work on those architectures.

5.c. Stabilizing ebuilds

Only architecture maintainers for a given architecture should mark packages as stable on that architecture. The maintainer of the package should always be contacted just in case there are reasons not to do so. The exception to this is if you are part of an architecture team, in which case you may mark the package stable for that architecture. If you are not part of an architecture team, you should consult the guidelines below; if the architecture you are looking for is not listed then please consult the relevant lead.

You should never stabilize packages on architectures for which you cannot test and instead you should file a bug to the relevant architecture team, such as sparc@gentoo.org asking them to stabilize the ebuild. Alternatively, you may be able to find Gentoo developers on IRC who could help you with your request.

It is best to not use arch-maintainers@gentoo.org, adding architecture teams onto a bug's CC list individually instead. That way teams can remove themselves from the list when they are done, giving a clear indication of which teams still have to stabilize a package.

5.d. Stabilization rules

SPARC: You must have prior permission from the arch lead (currently Weeve). Usually we expect you to be on the sparc alias for QA reasons, although other arrangements can be made if you will only be working with a small group of packages.

ALPHA: Maintainers may keyword their own packages but are reminded to inform the Alpha team if they can help out with testing and keywording packages so the team can keep an eye out for possible keywording mistakes.

MIPS: You must have prior permission from any senior MIPS developer. Because of the massive range of hardware involved, being on the mips alias and having access to a variety of MIPS systems are generally requirements.

5.e. Upgrading ebuilds

New ebuilds should rarely go in with "arch" keywords and even if they do not, the package must be tested on any architectures listed in the KEYWORDS variable of the new ebuild.

Exceptions to the no "arch" rule are major bug fixes, or security fixes. If the previous version of the ebuild contains KEYWORDS which you cannot test for, you should downgrade them: turn any "arch" keyword to "~arch". If you think that your package may not work at all even on "~arch" then it is best to leave the keyword out and request testing from the relevant team: if you are to do this, you must file a bug to the team in question.

If a new version introduces new dependencies which are not available on some architectures, then you should file a bug or ask on IRC before you upgrade the package. If you really need to get the ebuild added in a hurry, for example, for a security fix, then you should drop any KEYWORDS which are causing problems and CC the relevant architectures on the bug - you should file a new bug to the architecture in question regarding this if no bug is already available.

If there are no new dependencies, do not remove keywords if your commit fails with repoman - please try a full cvs update and if you still have problems, then commit with repoman -I and file a bug to the broken architecture, noting it in your CVS commit message.

5.f. Moving ebuilds

Moving ebuilds is a two-step process:

Firstly, you need to move the ebuild in CVS. To do this, you should copy the ebuild to its new location and commit that as you would with a new ebuild.

After this, you should change any ebuilds which DEPEND on the old ebuild to depend on the new one. After this, should add an entry to the latest file in profiles/updates/ in the Portage tree in the in the following format:

move net-misc/fwbuilder net-firewall/fwbuilder

This example would transparently move net-misc/fwbuilder to net-firewall/fwbuilder if users have it installed. This way, users would now automatically receive updates for net-firewall/fwbuilder when they are available.

Once this step is concluded, you are allowed to remove the old package. Simply issue a cvs remove -Rf $PN in the package category and commit the changes afterwards with a meaningful commit message.

net-misc # cvs rm -Rf fwbuilder
cvs remove: use `cvs commit' to remove these files permanently
net-misc # cvs ci -m "Moving net-misc/fwbuilder to net-firewall/fwbuilder."

5.g. Removing ebuilds

When removing an ebuild make sure that no dependencies in Portage are broken due to the removal - additionally, your CVS commit message should explain clearly why the ebuild is being removed from CVS.

If you need to remove ebuilds, make sure you do not accidentally remove the newest/only stable ebuild for any architecture. If you would like to get a newer version marked stable, then please file a bug or ask on IRC.

You should also not cause an unnecessary downgrade for any "~arch" when removing ebuilds - instead, it is best to get the newest version marked "~arch" first and then remove redundant versions of the ebuild.

5.h. Removing a package

When removing an ebuild make sure that no dependencies in Portage are broken due to the removal - additionally, your CVS commit message should explain clearly why the ebuild is being removed from CVS.

In order to remove a package completely from CVS, delete any files from the directory and commit this, CVS will take care of removing empty directories itself.

# cd app-admin
# cvs rm -Rf scotty
# cvs ci -m "app-admin/scotty removal (pending 21st July 2006), see #77501 for reference." scotty

5.i. Conflicting files

When you encounter a package that is trying to install files that are already provided by another package (detectable with FEATURES=collision-protect for example) you have to fix this situation before you can commit the ebuild or, if you encounter this with an existing package, file a bug about that package (see below for a few exceptions). The reason file conflicts are critical is because if "foo" provides the file /usr/bin/example and "bar" is going to overwrite it, and later "bar" is unmerged, Portage will remove /usr/bin/example and it is therefore likely it will break "foo".

The most obvious fix is to add a blocking dependency to both packages that want to install that file, so they can't be installed at the same time. But unless there are also other reasons for those packages to block each other you should avoid this if possible and rather fix the package, which could include one or more of the following steps:

• Make "foo" (R)DEPEND on "bar" and not install the conflicting file.
• Remove conflicting files from "foo" in src_install or pkg_preinst.
• Move conflicting files into a new subpackage and make "foo" and "bar" both (R)DEPEND on that package.
• Change the location where "foo" or "bar" installs conflicting files.

In some cases conflicting files can't be really fixed or aren't critical, currently known exceptions are Perl module manpages (overwriting the ones from Perl itself) and CONFIG_PROTECT'ed files (which should still be fixed, but aren't critical as Portage won't overwrite them).

[ << ] [ < ] [ Home ] [ > ] [ >> ]

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.