aboutsummaryrefslogtreecommitdiff
blob: d18d3337fb2ded7d915e29b2f042b0e4f6f62c5e (plain)
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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
<?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>
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:
</p>
<ol>
  <li>
    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
    accidentally.
  </li>

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

  <li>
    Otherwise, the change can be done in place in the current revision
    of the ebuild.
  </li>
</ol>

<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>

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