Ebuilds may have a Gentoo revision number associated with them. This is a
<c>-rX</c> suffix, where <c>X</c> is an integer <d/> see <uri
link="::ebuild-writing/file-format#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 <c>-r0</c>
<p>Ebuild revisions usually serve two purposes:</p>
keeping an older copy of an ebuild around when doing a potentially
breaking change, and
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 <c>-rX</c> revision. The following rule
of thumb could be used as a guideline:
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 <c>~arch</c> (see
<uri link="::keywording#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
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, <c>repoman commit
--straight-to-stable</c> option should be used.
Otherwise, the change can be done in place in the current revision
of the ebuild.
<p>Examples of changes that warrant a new revision are:</p>
<li>adding a patch to fix a runtime issue,</li>
<li>installing additional files that could be useful to the user,</li>
<li>adding a missing runtime dependency to one of the existing blocks,</li>
adding a missing build-time dependency that contributed to
a successfully yet incorrect build (e.g. missing some feature),
restricting a runtime dependency version, unless the <c>:=</c>
subslot operator is going to trigger a rebuild.
<p>Examples of changes that can be done without a revision bump are:</p>
adding a patch to fix a build-time issue that prevented users from
building the package (since it does not affect users who already
managed to build it),
<li>adding a trivial documentation fix,</li>
installing an additional file of relatively little value (minor
documentation, editor syntax file, bash completion) compared
to the cost of rebuilding the package (especially if a new bump
is expected soon),
adding a missing build-time dependency that caused a build failure,
adding a new USE flag or removing an existing one (since change
in USE flags is going to trigger <c>--changed-use</c> rebuild),
a trivial stylistic / ebuild code change (as long as the new code
is equivalent to the old code),
a dependency change that is a result of a package move (slot move).