Ebuild revisions

Ebuilds may have a Gentoo revision number associated with them. This is a -rX suffix, where X is an integer — see File naming rules. This component must only be used for Gentoo changes, not upstream releases. An ebuild with no explicit revision number has the implicit -r0 revision.

Ebuild revisions usually serve two purposes:

  1. keeping an older copy of an ebuild around when doing a potentially breaking change, and
  2. propagating the rebuild of a package when performing a meaningful change that would otherwise go unnoticed by users who have installed the current version already.

Developers are encouraged to use common sense when determining whether to introduce a new -rX revision. The following rule of thumb could be used as a guideline:

  1. If the change can cause the package to be broken to the point of requiring users to revert to the previous version (in the case of packages marked stable, every non-trivial change is classified as such), then a new revision should be introduced and the old one kept. If the package has stable keywords, the new revision should be dropped to ~arch (see Keywording on upgrades). For any such revision bump, the new ebuild should be based on the previous revision to ensure that fixes aren't dropped accidentally.
  2. If the change makes a substantial difference to the user who already installed the package (fixes runtime issues, changes installed files, etc.) and it would not be propagated using other means, then the ebuild should be renamed to a new revision. If the package has stable keywords, they should be moved to the new revision without dropping. To commit the ebuild, pkgdev commit or git commit paired with pkgcheck scan --commits should be used).
  3. Otherwise, the change can be done in place in the current revision of the ebuild.

Examples of changes that warrant a new revision are:

Examples of changes that can be done without a revision bump are: