aboutsummaryrefslogtreecommitdiff
blob: 8248a6e23f78ea66aba54e0b6b7f9b986fd5d82f (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
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
<?xml version="1.0" encoding="UTF-8"?>
<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>pkgdev commit</c> or <c>git
    commit</c> paired with <c>pkgcheck scan --commits</c> should be used).
  </li>

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

<p>Examples of changes that warrant a new revision are:</p>
<ul>
  <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>
  <li>adding a binding subslot operator (:=) to a dependency,</li>
  <li>updating a dependency with default on/off USE flags,</li>
  <li>fixing an automagic dependency detection from a build system,</li>
  <li>
    restricting a runtime dependency version, unless the <c>:=</c>
    subslot operator is going to trigger a rebuild,
  </li>
  <li>
    updating the license, if any of the affected licenses is either non-free or
    is about to be removed,
  </li>
  <li>
    changing the EAPI (unless changes to the ebuild are trivial, and you can be
    sure it won't break stable or reverse dependencies).
  </li>
</ul>

<p>Examples of changes that can be done without a revision bump are:</p>
<ul>
  <li>
    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) unless: it affected runtime behaviour in some way
    (e.g. <c>-Wformat</c> or <c>-Wimplicit-function-declaration</c> fixes);
    the package may have been miscompiled, or the change is substantial
    (if adding a huge patch to fix a problem, the chances of an unexpected
    issue being introduced by it are greater).
  </li>
  <li>adding a trivial documentation fix,</li>
  <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),
  </li>
  <li>
    adding a missing build-time dependency that caused a build failure
    (unless it is also a runtime dependency),
  </li>
  <li>
    adding a new USE flag if it controls a USE-dependency where the
    functionality was hard-disabled in the build system before,
  </li>
  <li>
    removing an existing USE flag if it controls a USE-dependency where the
    functionality is now disabled entirely, rather than always being enabled
    (since the change in USE flags is going to trigger a <c>--changed-use</c>
    rebuild),
  </li>
  <li>
    a trivial stylistic / ebuild code change (as long as the new code
    is equivalent to the old code),
  </li>
  <li>
    a dependency change that is a result of a package move (slot move),
  </li>
</ul>

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