general-concepts/ebuild-revisions/text.xml


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

<?xml version="1.0"?>
<guide self="general-concepts/ebuild-revisions/">
<chapter>
<title>Ebuild Revisions</title>

<body>
<p>
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>
revision.
</p>

<p>Ebuild revisions usually serve two purposes:</p>
<ol>
  <li>
    keeping an older copy of an ebuild around when doing a potentially
    breaking change, and
  </li>

  <li>
    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.
  </li>
</ol>

<p>
Ebuilds should have their <c>-rX</c> incremented whenever a change is made which
will make a substantial difference to what gets installed by the package <d/> by
substantial, we generally mean "something for which many users would want to
upgrade". This is usually for bugfixes.
For any such revision bump, the new ebuild should be based on the
previous revision to ensure that fixes aren't dropped accidentally.
</p>

<p>
Simple compile fixes do <b>not</b> warrant a revision bump; this is because they do
not affect the installed package for users who already managed to compile it.
Small documentation fixes are also usually not grounds for a new revision.
In particular, this applies if the package has a substantial compilation
time; developers should use their best judgement in these circumstances.
</p>

<important>
For ebuilds marked stable on at least one arch, only trivial edits can be made
without a bump (e.g. typo fixes in elog messages). Even simple changes may
result in a breakage. <b>Modifying stable ebuilds should be avoided.</b>
</important>

<p>
When doing a revision bump, the usual rules about dropping to <c>~arch</c> apply.
See <uri link="::keywording#Keywording on Upgrades"/>.
</p>

</body>
</chapter>
</guide>