| 1 |
commit: d2e77eb8f1abe200a4c0ede569fa169c08205545 |
| 2 |
Author: Michał Górny <mgorny <AT> gentoo <DOT> org> |
| 3 |
AuthorDate: Sat Oct 14 09:40:48 2017 +0000 |
| 4 |
Commit: Göktürk Yüksek <gokturk <AT> gentoo <DOT> org> |
| 5 |
CommitDate: Wed Jan 3 01:20:19 2018 +0000 |
| 6 |
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=d2e77eb8 |
| 7 |
|
| 8 |
Convert 'Ebuild Maintenance' into a section |
| 9 |
|
| 10 |
The committer has reflowed some of the lines past 80 characters. |
| 11 |
|
| 12 |
.../{ => maintenance-tasks}/text.xml | 62 +- |
| 13 |
ebuild-maintenance/text.xml | 670 +-------------------- |
| 14 |
2 files changed, 44 insertions(+), 688 deletions(-) |
| 15 |
|
| 16 |
diff --git a/ebuild-maintenance/text.xml b/ebuild-maintenance/maintenance-tasks/text.xml |
| 17 |
similarity index 92% |
| 18 |
copy from ebuild-maintenance/text.xml |
| 19 |
copy to ebuild-maintenance/maintenance-tasks/text.xml |
| 20 |
index 0a94d9c..ba401ca 100644 |
| 21 |
--- a/ebuild-maintenance/text.xml |
| 22 |
+++ b/ebuild-maintenance/maintenance-tasks/text.xml |
| 23 |
@@ -1,7 +1,7 @@ |
| 24 |
<?xml version="1.0"?> |
| 25 |
-<guide self="ebuild-maintenance/"> |
| 26 |
+<guide self="ebuild-maintenance/maintenance-tasks/"> |
| 27 |
<chapter> |
| 28 |
-<title>Ebuild Maintenance</title> |
| 29 |
+<title>Maintenance Tasks</title> |
| 30 |
|
| 31 |
<body> |
| 32 |
<p> |
| 33 |
@@ -33,17 +33,18 @@ select all possible fields, then submit the query. For you lazy people, click |
| 34 |
<p> |
| 35 |
In general, the Gentoo repository should only be used for storing |
| 36 |
<path>.ebuild</path> files, as well as any relatively small companion |
| 37 |
-files, such as patches or sample configuration files. These types of |
| 38 |
-files should be placed in the <path>/usr/portage/mycat/mypkg/files</path> |
| 39 |
-directory to keep the main <path>mycat/mypkg</path> directory uncluttered. |
| 40 |
-Exceptions to this rule are for larger patch files (we recommend this for patches |
| 41 |
-above 20KB) which should be distributed as tarballs via the |
| 42 |
-<uri link="::general-concepts/mirrors/#suitable-download-hosts">Gentoo mirror system</uri> |
| 43 |
-so that people do not waste excessive amounts of bandwidth and hard drive |
| 44 |
-space. Also, you should not add binary (non-ASCII) files to the |
| 45 |
-git tree. Also, speaking of merging |
| 46 |
-changes, any patches you add to Portage should generally <e>not</e> be |
| 47 |
-compressed. This will allow git to merge changes and correctly inform |
| 48 |
+files, such as patches or sample configuration files. These types of |
| 49 |
+files should be placed in the |
| 50 |
+<path>/usr/portage/mycat/mypkg/files</path> directory to keep the main |
| 51 |
+<path>mycat/mypkg</path> directory uncluttered. Exceptions to this |
| 52 |
+rule are for larger patch files (we recommend this for patches above |
| 53 |
+20KB) which should be distributed as tarballs via the |
| 54 |
+<uri link="::general-concepts/mirrors/#suitable-download-hosts">Gentoo |
| 55 |
+mirror system</uri> so that people do not waste excessive amounts of |
| 56 |
+bandwidth and hard drive space. Also, you should not add binary |
| 57 |
+(non-ASCII) files to the git tree. Also, speaking of merging changes, |
| 58 |
+any patches you add to Portage should generally <e>not</e> be |
| 59 |
+compressed. This will allow git to merge changes and correctly inform |
| 60 |
developers of conflicts. |
| 61 |
</p> |
| 62 |
|
| 63 |
@@ -303,7 +304,12 @@ critical issue that needs to be handled ASAP. Otherwise a soft limit |
| 64 |
of 2 to 4 weeks depending on the severity of the bug is an acceptable |
| 65 |
time frame before you go ahead and fix it yourself. |
| 66 |
</p> |
| 67 |
-<important> Common sense dictates to us that toolchain/base-system/core packages and eclasses or anything else which is delicate (e.g. glibc) or widely used (e.g. gtk+) should usually be left to those maintainers. If in doubt, don't touch it.</important> |
| 68 |
+<important> |
| 69 |
+Common sense dictates to us that toolchain/base-system/core packages |
| 70 |
+and eclasses or anything else which is delicate (e.g. glibc) or widely |
| 71 |
+used (e.g. gtk+) should usually be left to those maintainers. If in |
| 72 |
+doubt, don't touch it. |
| 73 |
+</important> |
| 74 |
|
| 75 |
<p> |
| 76 |
Respect developers' coding preferences. Unnecessarily changing the |
| 77 |
@@ -367,10 +373,16 @@ the team can keep an eye out for possible keywording mistakes. |
| 78 |
</p> |
| 79 |
|
| 80 |
<p> |
| 81 |
-Exotic architectures (like alpha, ia64, sparc, hppa, ppc*) are short on manpower, so it's best if you avoid opening stabilization bugs for them unless it is absolutely necessary (eg, a reverse dependency for your package). More about keywording policies can be found in the <uri link="::keywording">keywording</uri> section. |
| 82 |
+Exotic architectures (like alpha, ia64, sparc, hppa, ppc*) are short |
| 83 |
+on manpower, so it's best if you avoid opening stabilization bugs for |
| 84 |
+them unless it is absolutely necessary (eg, a reverse dependency for |
| 85 |
+your package). More about keywording policies can be found in the |
| 86 |
+<uri link="::keywording">keywording</uri> section. |
| 87 |
</p> |
| 88 |
<p> |
| 89 |
-Some architectures (like m68k, mips, s390, sh) do not maintain a stable keyword. So there is no use in marking a package stable for one of these architectures. |
| 90 |
+Some architectures (like m68k, mips, s390, sh) do not maintain a |
| 91 |
+stable keyword. So there is no use in marking a package stable for one |
| 92 |
+of these architectures. |
| 93 |
</p> |
| 94 |
</body> |
| 95 |
</section> |
| 96 |
@@ -522,18 +534,20 @@ Date: Tue Nov 3 20:26:52 2015 +0100 |
| 97 |
<title>Changing ebuild's SLOT</title> |
| 98 |
<body> |
| 99 |
<p> |
| 100 |
-The process for changing the ebuild's SLOT is very similar to the previous process. |
| 101 |
-Besides changing the SLOT in the ebuild file, you also need to create a new entry |
| 102 |
-in <path>profiles/updates/</path> in the Gentoo repository in the following format: |
| 103 |
+The process for changing the ebuild's SLOT is very similar to the |
| 104 |
+previous process. Besides changing the SLOT in the ebuild file, you |
| 105 |
+also need to create a new entry in <path>profiles/updates/</path> in |
| 106 |
+the Gentoo repository in the following format: |
| 107 |
</p> |
| 108 |
|
| 109 |
<pre caption="Adding an entry to updates"> |
| 110 |
slotmove app-text/gtkspell 0 2 |
| 111 |
</pre> |
| 112 |
|
| 113 |
-<p>Make sure that you have fixed all the reverse dependencies and that you have |
| 114 |
-updated every file in <path>profiles/</path> directory that happens to contain an |
| 115 |
-entry which may be affected by your change. |
| 116 |
+<p> |
| 117 |
+Make sure that you have fixed all the reverse dependencies and that |
| 118 |
+you have updated every file in <path>profiles/</path> directory that |
| 119 |
+happens to contain an entry which may be affected by your change. |
| 120 |
</p> |
| 121 |
|
| 122 |
</body> |
| 123 |
@@ -573,7 +587,9 @@ When removing packages follow these steps: |
| 124 |
</p> |
| 125 |
|
| 126 |
<ol> |
| 127 |
- <li>Make sure that no dependencies in Portage are broken due to the removal</li> |
| 128 |
+ <li> |
| 129 |
+ Make sure that no dependencies in Portage are broken due to the removal |
| 130 |
+ </li> |
| 131 |
<li>Send last rites to gentoo-dev-announce and gentoo-dev</li> |
| 132 |
<li>Mask the package</li> |
| 133 |
<li>Wait 30 days (or more)</li> |
| 134 |
|
| 135 |
diff --git a/ebuild-maintenance/text.xml b/ebuild-maintenance/text.xml |
| 136 |
index 0a94d9c..46ab82f 100644 |
| 137 |
--- a/ebuild-maintenance/text.xml |
| 138 |
+++ b/ebuild-maintenance/text.xml |
| 139 |
@@ -5,677 +5,17 @@ |
| 140 |
|
| 141 |
<body> |
| 142 |
<p> |
| 143 |
-This guide aims to explain common everyday ebuild maintenance |
| 144 |
-routines, as well as other rarer maintenance routines which |
| 145 |
-developers may not be familiar with. |
| 146 |
+This section covers various tasks related to working with ebuilds. |
| 147 |
</p> |
| 148 |
- |
| 149 |
-<section> |
| 150 |
-<title>Adding a new ebuild</title> |
| 151 |
-<body> |
| 152 |
- |
| 153 |
-<subsection> |
| 154 |
-<title>What (not) to put in the Gentoo repository</title> |
| 155 |
-<body> |
| 156 |
- |
| 157 |
-<p> |
| 158 |
-Before writing a new ebuild, check |
| 159 |
-<uri link="https://bugs.gentoo.org/">bugs.gentoo.org</uri> |
| 160 |
-to see if an ebuild has already been written for the package, but has not yet |
| 161 |
-been added to the Gentoo repository. Go to <uri |
| 162 |
-link="https://bugs.gentoo.org/">bugs.gentoo.org</uri>, choose query and select |
| 163 |
-Advanced Search; as product select <e>Gentoo Linux</e>, as component select |
| 164 |
-<e>ebuilds</e>. In the search field put the name of the ebuild and as status |
| 165 |
-select all possible fields, then submit the query. For you lazy people, click |
| 166 |
-<uri link="https://bugs.gentoo.org/query.cgi?format=advanced&product=Gentoo%20Linux&component=New%20Ebuilds&bug_Status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=IN_PROGRESS&bug_status=RESOLVED&bug_status=VERIFIED">here</uri>. |
| 167 |
-</p> |
| 168 |
- |
| 169 |
-<p> |
| 170 |
-In general, the Gentoo repository should only be used for storing |
| 171 |
-<path>.ebuild</path> files, as well as any relatively small companion |
| 172 |
-files, such as patches or sample configuration files. These types of |
| 173 |
-files should be placed in the <path>/usr/portage/mycat/mypkg/files</path> |
| 174 |
-directory to keep the main <path>mycat/mypkg</path> directory uncluttered. |
| 175 |
-Exceptions to this rule are for larger patch files (we recommend this for patches |
| 176 |
-above 20KB) which should be distributed as tarballs via the |
| 177 |
-<uri link="::general-concepts/mirrors/#suitable-download-hosts">Gentoo mirror system</uri> |
| 178 |
-so that people do not waste excessive amounts of bandwidth and hard drive |
| 179 |
-space. Also, you should not add binary (non-ASCII) files to the |
| 180 |
-git tree. Also, speaking of merging |
| 181 |
-changes, any patches you add to Portage should generally <e>not</e> be |
| 182 |
-compressed. This will allow git to merge changes and correctly inform |
| 183 |
-developers of conflicts. |
| 184 |
-</p> |
| 185 |
- |
| 186 |
-<p> |
| 187 |
-Remember, the packages that you commit must be <e>ready</e> <e>out of the |
| 188 |
-box</e> for end users when committed as stable. Make sure that you have a good |
| 189 |
-set of default settings that will satisfy the majority of systems and |
| 190 |
-users that will use your package. If your package is broken, and you are |
| 191 |
-not sure how to get it to work, check some other distributions that have |
| 192 |
-done their own versions of the package. You can check |
| 193 |
-<uri link="http://cvs.mandriva.com/cgi-bin/viewvc.cgi/SPECS/">Mandriva</uri> |
| 194 |
-or <uri link="http://www.debian.org/distrib/packages">Debian</uri> or |
| 195 |
-<uri link="http://pkgs.fedoraproject.org/cgit/rpms/">Fedora</uri> for some |
| 196 |
-examples. |
| 197 |
-</p> |
| 198 |
- |
| 199 |
-<p> |
| 200 |
-When committing to git, all developers should use <c>repoman commit</c> |
| 201 |
-instead of <c>git commit</c> to submit their ebuilds. Before committing, |
| 202 |
-please run <c>repoman full</c> to make sure you didn't forget something. |
| 203 |
-</p> |
| 204 |
- |
| 205 |
-</body> |
| 206 |
-</subsection> |
| 207 |
- |
| 208 |
-<subsection> |
| 209 |
-<title>Initial Architecture Keywords</title> |
| 210 |
-<body> |
| 211 |
-<p> |
| 212 |
-When adding a new ebuild, you should only include <c>KEYWORDS</c> for |
| 213 |
-architectures on which you have actually tested the ebuild, confirming |
| 214 |
-that it works as it should and that <c>USE</c> flags are properly |
| 215 |
-honoured in the resulting package which would be installed. If |
| 216 |
-possible, you should give the actual library or application thorough |
| 217 |
-testing as well, since you would be responsible for any breakages for |
| 218 |
-your architecture(s). Minimal testing such as checking that the |
| 219 |
-application starts up without any errors should always be performed. |
| 220 |
-</p> |
| 221 |
- |
| 222 |
-<p> |
| 223 |
-If you are adding a user-submitted ebuild, do not assume that the |
| 224 |
-submitter has done testing on various architectures: often, <c>KEYWORDS</c> |
| 225 |
-are cloned across packages or generated from documentation in the |
| 226 |
-source packages, which does not signify that the package does indeed |
| 227 |
-work on those architectures. |
| 228 |
-</p> |
| 229 |
- |
| 230 |
-</body> |
| 231 |
-</subsection> |
| 232 |
- |
| 233 |
-<subsection> |
| 234 |
-<title>Git Commit Message Format</title> |
| 235 |
-<body> |
| 236 |
- |
| 237 |
-<p> |
| 238 |
-It is important to format the commit messages properly so that they |
| 239 |
-communicate the changes to the reader in a clear and concise |
| 240 |
-way. Additionally, consistency in message format allows for easier |
| 241 |
-parsing by external tools. The first line of the commit message should |
| 242 |
-contain a brief summary of the changes, followed by an empty new |
| 243 |
-line. From the third line onward should be a detailed, multiline |
| 244 |
-explanation of the changes introduced by the commit. At the very end, |
| 245 |
-auxiliary information such as the bugs related to the commit, |
| 246 |
-contributors, and reviewers should be listed using RFC822/git style |
| 247 |
-tags. The length of the lines in the message should be 70-75 |
| 248 |
-characters at maximum. |
| 249 |
-</p> |
| 250 |
- |
| 251 |
-<p> |
| 252 |
-The summary line should start with referencing what is affected by the |
| 253 |
-change followed by a colon ':' character. Use the rules in the |
| 254 |
-following list to determine the proper format based on what has |
| 255 |
-changed, substituting the package, category and eclass names |
| 256 |
-appropriately: |
| 257 |
- |
| 258 |
-<ul> |
| 259 |
-<li><c>${CATEGORY}/${PN}:</c>Single Package (Note that <c>repoman commit</c> |
| 260 |
-automatically inserts this for you)</li> |
| 261 |
-<li><c>${CATEGORY}:</c> Package Category</li> |
| 262 |
-<li><c>profiles:</c> Profile Directory</li> |
| 263 |
-<li><c>${ECLASS}.eclass:</c> Eclass Directotry</li> |
| 264 |
-<li><c>licenses:</c> Licenses Directory</li> |
| 265 |
-<li><c>metadata:</c> Metadata Directory</li> |
| 266 |
-</ul> |
| 267 |
- |
| 268 |
-For packages where <c>${CATEGORY}/${PN}:</c> is long, the line length |
| 269 |
-limit can be exceeded, if absolutely necessary, to ensure a more |
| 270 |
-useful summary line. If a commit affects multiple directories, prepend |
| 271 |
-the message with which reflects the intention of the change best. If |
| 272 |
-there are any bugs on Gentoo Bugzilla associated with the commit, id |
| 273 |
-of the bug can be appended to the summary line using the format |
| 274 |
-<c>#BUG-ID</c>. If you are modifying keywords, clearly state what |
| 275 |
-keywords are added/removed. |
| 276 |
- |
| 277 |
-<warning> |
| 278 |
-By default, lines starting with <c>#</c> are considered to be comments |
| 279 |
-by git and not included in the commit message. Make sure that a new |
| 280 |
-line does not start with <c>#BUG-ID</c>. Optionally, git can be |
| 281 |
-configured to use a different character for comments by changing the |
| 282 |
-<c>commentchar</c> option. |
| 283 |
-</warning> |
| 284 |
-</p> |
| 285 |
- |
| 286 |
-<p> |
| 287 |
-For non-trivial commits, the message should contain a detailed |
| 288 |
-explanation of what the commit intends to change, why it is required, |
| 289 |
-and how it is accomplished, along with any other supplementary |
| 290 |
-information. |
| 291 |
-</p> |
| 292 |
- |
| 293 |
-<p> |
| 294 |
-Finally the commit message should list auxiliary information such as |
| 295 |
-people who are involved in authoring, suggesting, reviewing and |
| 296 |
-testing the changes, and revelant bugs. Use RFC822/git style tags as |
| 297 |
-explained in the |
| 298 |
-<uri link="https://kernel.org/doc/html/latest/process/submitting-patches.html"> |
| 299 |
-Linux Kernel patch guideline</uri>. Additionally, the following tags |
| 300 |
-are optionally used in Gentoo: |
| 301 |
- |
| 302 |
-<ul> |
| 303 |
-<li><c>Bug:</c> Use this to reference bugs <e>without</e> closing them. |
| 304 |
-The value is a URL to the bug. If multiple bugs need to be referenced, |
| 305 |
-each one should be listed in a separate <c>Bug</c> tag. If a bug |
| 306 |
-on Gentoo Bugzilla, or an issue or a pull request on GitHub |
| 307 |
-is referenced, a reference to the commit will be added |
| 308 |
-automatically.</li> |
| 309 |
-<li><c>Closes:</c> Use this to reference bugs and close them |
| 310 |
-automatically. Alike <c>Bug:</c>, the value is a single URL to the bug, |
| 311 |
-and multiple tags can be used to close multiple bugs. If a bug on Gentoo |
| 312 |
-Bugzilla, or an issue or a pull request on a GitHub repository |
| 313 |
-mirrored by Gentoo is referenced, it will be closed (as fixed) |
| 314 |
-automatically with reference to the commit.</li> |
| 315 |
-<li><c>Package-Manager:</c> This is automatically inserted by |
| 316 |
-<c>repoman commit</c> and it specifies the version of |
| 317 |
-<pkg>sys-apps/portage</pkg> on the system.</li> |
| 318 |
-<li><c>RepoMan-Options:</c> This is automatically inserted by |
| 319 |
-<c>repoman commit</c> and records the options passed to repoman (such |
| 320 |
-as --force) for the commit.</li> |
| 321 |
-</ul> |
| 322 |
-</p> |
| 323 |
- |
| 324 |
-<p> |
| 325 |
-Additionally, some developers prefer referencing bugs on the summary |
| 326 |
-line using the <c>#nnnnnn</c> form. Developers are free to use either |
| 327 |
-form, or both simultaneously to combine their advantages. |
| 328 |
-</p> |
| 329 |
- |
| 330 |
-<p> |
| 331 |
-When committing <uri link="::ebuild-writing/user-submitted">user |
| 332 |
-contributions</uri>, make sure to credit them in your commit message |
| 333 |
-with the user's full name and email address. Be aware and respectful |
| 334 |
-of their privacy: some users prefer to be only known by a |
| 335 |
-nickname. Take advantage of the tags such as <c>Suggested-By</c> or |
| 336 |
-<c>Reported-By:</c>when entering such information to the commit |
| 337 |
-message. |
| 338 |
-</p> |
| 339 |
- |
| 340 |
-<p> |
| 341 |
-An example commit message is shown below: |
| 342 |
-</p> |
| 343 |
- |
| 344 |
-<pre caption="Example commit message"> |
| 345 |
-app-misc/foo: version bump to 0.5 |
| 346 |
- |
| 347 |
-This also adds a new USE flag 'bar' which controls the |
| 348 |
-new bar functionality introduced with this version. |
| 349 |
- |
| 350 |
-Bug: https://bugs.gentoo.org/00000 |
| 351 |
-Closes: https://bugs.gentoo.org/00001 |
| 352 |
-</pre> |
| 353 |
- |
| 354 |
</body> |
| 355 |
-</subsection> |
| 356 |
- |
| 357 |
-<subsection> |
| 358 |
-<title>Git Commit Policy</title> |
| 359 |
-<body> |
| 360 |
- |
| 361 |
-<ul> |
| 362 |
-<li>Always run <c>repoman scan</c> before you commit.</li> |
| 363 |
-<li>Please run <c>repoman full</c> before you commit.</li> |
| 364 |
-<li>Always test that <path>package.mask</path> is okay by doing |
| 365 |
-<c>emerge --pretend mypkg</c> before you commit and check |
| 366 |
-that it doesn't contain any conflicts.</li> |
| 367 |
-<li>Always commit the updated <path>package.mask</path> before |
| 368 |
-the updated package.</li> |
| 369 |
-<li>Always do atomic commits; if you commit a package with a new license, |
| 370 |
-or that is masked, then first commit the revised <path>package.mask</path> and/or license, |
| 371 |
-then commit the ebuild, patches |
| 372 |
-and <uri link="::ebuild-writing/misc-files/metadata">metadata.xml</uri> all in <b>one</b> go |
| 373 |
-.</li> |
| 374 |
-<note> Although the set of changes in a single git commit is atomic, and |
| 375 |
-combining <path>package.mask</path>/license changes with ebuild changes in a |
| 376 |
-single commit wouldn't break atomicity, it is not currently possible to do so |
| 377 |
-using <c>repoman commit</c>.</note> |
| 378 |
-<!-- See: https://bugs.gentoo.org/show_bug.cgi?id=390651 --> |
| 379 |
-</ul> |
| 380 |
- |
| 381 |
-</body> |
| 382 |
-</subsection> |
| 383 |
- |
| 384 |
-<subsection> |
| 385 |
-<title>The files Directory</title> |
| 386 |
-<body> |
| 387 |
- |
| 388 |
-<p> |
| 389 |
-As noted earlier, under each package subdirectory is |
| 390 |
-a <path>files/</path> directory. Any patches, configuration files, or |
| 391 |
-other ancillary files your package might require should be added to |
| 392 |
-this directory; any files bigger than 20KB-or-so should go to the |
| 393 |
-mirrors to lower the amount of (unneeded) files our users have to |
| 394 |
-download. You may want to consider naming patches you create yourself |
| 395 |
-just to get your package to build with a version-specific name, such |
| 396 |
-as <path>mypkg-1.0-gentoo.diff</path>, or more |
| 397 |
-simply, <path>1.0-gentoo.diff</path>. Also note that the |
| 398 |
-<path>gentoo</path> extension informs people that this patch was created |
| 399 |
-by us, the Gentoo Linux developers, rather than having been grabbed from a |
| 400 |
-mailing list or somewhere else. Again, you should not compress these |
| 401 |
-patches. |
| 402 |
-</p> |
| 403 |
- |
| 404 |
-<p> |
| 405 |
-Consider prefixing or suffixing (such as <path>mypkg-1.0</path>) every file |
| 406 |
-you put into the <path>files/</path> directory, so that the files used for |
| 407 |
-each individual version on an ebuild are distinguishable from one another, and |
| 408 |
-so that the changes between different revisions are visible. This is generally |
| 409 |
-a really good idea :). You may want to use a different suffix if you wish to |
| 410 |
-convey more meaning with the patch name. |
| 411 |
-</p> |
| 412 |
- |
| 413 |
-<p> |
| 414 |
-If you have many files that should go into the <path>files/</path> directory, |
| 415 |
-consider creating subdirectories such as <path>files/1.0/</path> and putting the |
| 416 |
-relevant files in the appropriate subdirectory. If you use this method, |
| 417 |
-you do not need to add version information to the names of the files, |
| 418 |
-which is often more convenient. |
| 419 |
-</p> |
| 420 |
- |
| 421 |
-</body> |
| 422 |
-</subsection> |
| 423 |
- |
| 424 |
-</body> |
| 425 |
-</section> |
| 426 |
|
| 427 |
<section> |
| 428 |
-<title>Touching other developers ebuilds</title> |
| 429 |
+<title>Contents</title> |
| 430 |
<body> |
| 431 |
-<p> |
| 432 |
-Usually you don't just change other developers ebuilds without |
| 433 |
-permission unless you know that developer does not mind or if you are |
| 434 |
-part of the project involved in maintenance (this information can |
| 435 |
-typically be found in metadata.xml). Start with filing a bug or trying |
| 436 |
-to catch them on IRC or via email. Sometimes you cannot reach them, or |
| 437 |
-there is no response to your bug. It's a good idea to consult other |
| 438 |
-developers on how to handle the situation, especially if it's a |
| 439 |
-critical issue that needs to be handled ASAP. Otherwise a soft limit |
| 440 |
-of 2 to 4 weeks depending on the severity of the bug is an acceptable |
| 441 |
-time frame before you go ahead and fix it yourself. |
| 442 |
-</p> |
| 443 |
-<important> Common sense dictates to us that toolchain/base-system/core packages and eclasses or anything else which is delicate (e.g. glibc) or widely used (e.g. gtk+) should usually be left to those maintainers. If in doubt, don't touch it.</important> |
| 444 |
- |
| 445 |
-<p> |
| 446 |
-Respect developers' coding preferences. Unnecessarily changing the |
| 447 |
-syntax of an ebuild can cause complications for others. Syntax changes |
| 448 |
-should only be done if there is a real benefit, such as faster |
| 449 |
-compilation, improved information for the end user, or compliance with |
| 450 |
-Gentoo policies. |
| 451 |
-</p> |
| 452 |
- |
| 453 |
+<contentsTree/> |
| 454 |
</body> |
| 455 |
</section> |
| 456 |
- |
| 457 |
-<section> |
| 458 |
-<title>Stabilizing ebuilds</title> |
| 459 |
-<body> |
| 460 |
- |
| 461 |
-<p> |
| 462 |
-Only architecture maintainers for a given architecture should mark packages as |
| 463 |
-stable on that architecture. The maintainer of the package should always be |
| 464 |
-contacted just in case there are reasons not to do so. The exception to this |
| 465 |
-is if you are part of an architecture team, in which case you may mark the |
| 466 |
-package stable for that architecture. If you are not part of an architecture |
| 467 |
-team, you should consult the guidelines below; if the architecture you are |
| 468 |
-looking for is not listed then please consult the relevant lead. |
| 469 |
-</p> |
| 470 |
- |
| 471 |
-<p> |
| 472 |
-You should <e>never</e> stabilize packages on |
| 473 |
-architectures for which you cannot test and instead you should file a bug to |
| 474 |
-the relevant architecture team, such as <mail link="sparc@g.o"> |
| 475 |
-sparc@g.o</mail> asking them to stabilize the |
| 476 |
-ebuild. Alternatively, you may be able to find Gentoo developers on |
| 477 |
-IRC who could help you with your request. |
| 478 |
-</p> |
| 479 |
- |
| 480 |
-<p> |
| 481 |
-It is best to not use <mail link="arch-maintainers@g.o"> |
| 482 |
-arch-maintainers@g.o</mail>, adding architecture teams onto a |
| 483 |
-bug's CC list individually instead. That way teams can remove |
| 484 |
-themselves from the list when they are done, giving a clear indication |
| 485 |
-of which teams still have to stabilize a package. |
| 486 |
-</p> |
| 487 |
- |
| 488 |
-</body> |
| 489 |
-</section> |
| 490 |
- |
| 491 |
-<section> |
| 492 |
-<title>Stabilization rules</title> |
| 493 |
-<body> |
| 494 |
- |
| 495 |
-<p> |
| 496 |
-SPARC: You must have prior permission from the arch lead. Usually we expect |
| 497 |
-you to be on the sparc alias for QA reasons, although other arrangements |
| 498 |
-can be made if you will only be working with a small group of packages. |
| 499 |
-</p> |
| 500 |
- |
| 501 |
-<p> |
| 502 |
-ALPHA: Maintainers may keyword their own packages but are reminded to inform |
| 503 |
-the Alpha team if they can help out with testing and keywording packages so |
| 504 |
-the team can keep an eye out for possible keywording mistakes. |
| 505 |
-</p> |
| 506 |
- |
| 507 |
-<p> |
| 508 |
-Exotic architectures (like alpha, ia64, sparc, hppa, ppc*) are short on manpower, so it's best if you avoid opening stabilization bugs for them unless it is absolutely necessary (eg, a reverse dependency for your package). More about keywording policies can be found in the <uri link="::keywording">keywording</uri> section. |
| 509 |
-</p> |
| 510 |
-<p> |
| 511 |
-Some architectures (like m68k, mips, s390, sh) do not maintain a stable keyword. So there is no use in marking a package stable for one of these architectures. |
| 512 |
-</p> |
| 513 |
-</body> |
| 514 |
-</section> |
| 515 |
- |
| 516 |
-<section> |
| 517 |
-<title>Upgrading ebuilds</title> |
| 518 |
-<body> |
| 519 |
- |
| 520 |
-<p> |
| 521 |
-New ebuilds should rarely go in with "<c>arch</c>" keywords and even if they do |
| 522 |
-not, the package <e>must</e> be tested on any architectures listed in the |
| 523 |
-<c>KEYWORDS</c> variable of the new ebuild. |
| 524 |
-</p> |
| 525 |
- |
| 526 |
-<p> |
| 527 |
-Exceptions to the no "<c>arch</c>" rule are major bug fixes, or |
| 528 |
-security fixes. If the previous version of the ebuild |
| 529 |
-contains <c>KEYWORDS</c> which you cannot test for, you should |
| 530 |
-downgrade them: turn any "<c>arch</c>" keyword to "<c>~arch</c>". If you |
| 531 |
-think that your package may not work at all even on "<c>~arch</c>" |
| 532 |
-then it is best to leave the keyword out and request testing from the |
| 533 |
-relevant team: if you are to do this, you must file a bug to the team |
| 534 |
-in question. |
| 535 |
-</p> |
| 536 |
- |
| 537 |
-<p> |
| 538 |
-If a new version introduces new dependencies which are not available |
| 539 |
-on some architectures, then you should file a bug or ask on IRC before |
| 540 |
-you upgrade the package. If you really need to get the ebuild added in |
| 541 |
-a hurry, for example, for a security fix, then you should drop |
| 542 |
-any <c>KEYWORDS</c> which are causing problems and CC the relevant |
| 543 |
-architectures on the bug - you should file a new bug to the |
| 544 |
-architecture in question regarding this if no bug is already |
| 545 |
-available. |
| 546 |
-</p> |
| 547 |
- |
| 548 |
-<p> |
| 549 |
-If there are no new dependencies, do not remove keywords if your |
| 550 |
-commit fails with repoman - please try a full <c>git pull</c> and if |
| 551 |
-you still have problems, then commit with <c>repoman -I</c> and file a |
| 552 |
-bug to the broken architecture, noting it in your git commit message. |
| 553 |
-</p> |
| 554 |
- |
| 555 |
-<warning> |
| 556 |
-When committing, make sure that you reference any bugs in the |
| 557 |
-commit message. Failing to do so is considered |
| 558 |
-to be in very poor taste and may result in disciplinary action. |
| 559 |
-</warning> |
| 560 |
- |
| 561 |
-</body> |
| 562 |
-</section> |
| 563 |
- |
| 564 |
-<section> |
| 565 |
-<title>Moving a package</title> |
| 566 |
-<body> |
| 567 |
- |
| 568 |
-<p> |
| 569 |
-Moving a package in the tree requires several operations. Firstly, |
| 570 |
-the package directory needs to be moved to the correct category |
| 571 |
-using <c>git mv</c>. After this, a new entry needs to be added to |
| 572 |
-the latest file in <path>profiles/updates/</path> in the |
| 573 |
-following format: |
| 574 |
-</p> |
| 575 |
- |
| 576 |
-<pre caption="Adding an entry to updates"> |
| 577 |
-move old-category/package-name new-category/package-name |
| 578 |
-</pre> |
| 579 |
- |
| 580 |
-<p> |
| 581 |
-Following the update entry, ebuilds that have a |
| 582 |
-<uri link="::general-concepts/dependencies">dependency</uri> |
| 583 |
-to this package (in other words, the reverse dependencies of |
| 584 |
-the package to be moved) need to be updated properly. |
| 585 |
-</p> |
| 586 |
- |
| 587 |
-<p> |
| 588 |
-Next is checking the files under <path>profiles/</path> such as |
| 589 |
-<path>profiles/package.mask</path> and update them to reflect the ebuild |
| 590 |
-move. Various eclasses automatically provide some of the dependencies upon |
| 591 |
-inherit, so the files under <path>eclass/</path> should be checked and updated |
| 592 |
-properly. If the package metadata.xml has tags with <c>restrict</c> |
| 593 |
-attribute, they should be updated to reflect the move. The |
| 594 |
-metadata.xml for various packages may contain references to the |
| 595 |
-package being moved using the <c><pkg></c> tag which need to be |
| 596 |
-updated accordingly as well. Lastly, the titles of the open bugs |
| 597 |
-related to the package should be updated. |
| 598 |
-</p> |
| 599 |
- |
| 600 |
-<p> |
| 601 |
-Here is an example where the package |
| 602 |
-<path>net-misc/fwbuilder</path> is transparently moved to |
| 603 |
-<path>net-firewall/fwbuilder</path>: |
| 604 |
-</p> |
| 605 |
- |
| 606 |
-<ol> |
| 607 |
- <li>Issue <c>git mv net-misc/fwbuilder net-firewall/fwbuilder</c></li> |
| 608 |
- <li> |
| 609 |
- <p> |
| 610 |
- Add the following entry to the latest file in |
| 611 |
- <path>profile/updates/</path>: |
| 612 |
- </p> |
| 613 |
- <p><c>move net-misc/fwbuilder net-firewall/fwbuilder</c></p> |
| 614 |
- </li> |
| 615 |
- <li>Update the reverse dependencies of the package</li> |
| 616 |
- <li> |
| 617 |
- Update <path>profiles/package.mask</path> and other related files under |
| 618 |
- <path>profiles/</path> |
| 619 |
- </li> |
| 620 |
- <li>Check the eclasses that may be referencing the package</li> |
| 621 |
- <li> |
| 622 |
- Update all the |
| 623 |
- <uri link="::ebuild-writing/misc-files/metadata">metadata.xml</uri> |
| 624 |
- files which contain a reference to this package using the |
| 625 |
- <c><pkg></c> tag or the <c>restrict</c> attribute. |
| 626 |
- </li> |
| 627 |
- <li> |
| 628 |
- Stage all the changed files using <c>git add</c>. For example: <c>git add |
| 629 |
- profiles/package.mask</c> |
| 630 |
- </li> |
| 631 |
- <li> |
| 632 |
- Commit all the changes in one commit using: <c>git commit --gpg-sign</c> |
| 633 |
- </li> |
| 634 |
- <li> |
| 635 |
- Update any <uri link="::general-concepts/news">news items</uri> |
| 636 |
- referencing the package in a <c>Display-If-Installed</c> header |
| 637 |
- or in the item's body (and increment their <c>Revision</c>). |
| 638 |
- </li> |
| 639 |
- <li>Update any open bugs related to the package</li> |
| 640 |
-</ol> |
| 641 |
- |
| 642 |
-<p> |
| 643 |
-It is very important to commit all the changes in a single commit to ensure |
| 644 |
-that no breakage occurs. The commit message should follow a format similar |
| 645 |
-to the following: |
| 646 |
-</p> |
| 647 |
- |
| 648 |
-<pre> |
| 649 |
-commit d391643289097344a0b18ab2665bb26198a0e3a1 |
| 650 |
-Author: Guilherme Amadio <amadio@g.o> |
| 651 |
-Date: Tue Nov 3 20:26:52 2015 +0100 |
| 652 |
- |
| 653 |
- media-fonts/nanumfont: renamed to media-fonts/nanum |
| 654 |
-</pre> |
| 655 |
- |
| 656 |
-</body> |
| 657 |
-</section> |
| 658 |
- |
| 659 |
-<section> |
| 660 |
-<title>Changing ebuild's SLOT</title> |
| 661 |
-<body> |
| 662 |
-<p> |
| 663 |
-The process for changing the ebuild's SLOT is very similar to the previous process. |
| 664 |
-Besides changing the SLOT in the ebuild file, you also need to create a new entry |
| 665 |
-in <path>profiles/updates/</path> in the Gentoo repository in the following format: |
| 666 |
-</p> |
| 667 |
- |
| 668 |
-<pre caption="Adding an entry to updates"> |
| 669 |
-slotmove app-text/gtkspell 0 2 |
| 670 |
-</pre> |
| 671 |
- |
| 672 |
-<p>Make sure that you have fixed all the reverse dependencies and that you have |
| 673 |
-updated every file in <path>profiles/</path> directory that happens to contain an |
| 674 |
-entry which may be affected by your change. |
| 675 |
-</p> |
| 676 |
- |
| 677 |
-</body> |
| 678 |
-</section> |
| 679 |
- |
| 680 |
-<section> |
| 681 |
-<title>Removing ebuilds</title> |
| 682 |
-<body> |
| 683 |
- |
| 684 |
-<p> |
| 685 |
-When removing an ebuild make sure that no dependencies in Portage are broken |
| 686 |
-due to the removal - additionally, your git commit message should explain |
| 687 |
-clearly why the ebuild is being removed from the git repository. |
| 688 |
-</p> |
| 689 |
- |
| 690 |
-<p> |
| 691 |
-If you need to remove ebuilds, make sure you do not accidentally remove |
| 692 |
-the newest/only stable ebuild for any architecture. If you would like to |
| 693 |
-get a newer version marked stable, then please file a bug or ask on IRC. |
| 694 |
-</p> |
| 695 |
- |
| 696 |
-<p> |
| 697 |
-You should also not cause an unnecessary downgrade for any "<c>~arch</c>" |
| 698 |
-when removing ebuilds - instead, it is best to get the newest version |
| 699 |
-marked "<c>~arch</c>" first and then remove redundant versions of the ebuild. |
| 700 |
-</p> |
| 701 |
- |
| 702 |
-</body> |
| 703 |
-</section> |
| 704 |
- |
| 705 |
-<section> |
| 706 |
-<title>Removing a package</title> |
| 707 |
-<body> |
| 708 |
- |
| 709 |
-<p> |
| 710 |
-When removing packages follow these steps: |
| 711 |
-</p> |
| 712 |
- |
| 713 |
-<ol> |
| 714 |
- <li>Make sure that no dependencies in Portage are broken due to the removal</li> |
| 715 |
- <li>Send last rites to gentoo-dev-announce and gentoo-dev</li> |
| 716 |
- <li>Mask the package</li> |
| 717 |
- <li>Wait 30 days (or more)</li> |
| 718 |
- <li>Remove from the git tree unless the reason for removal has been fixed</li> |
| 719 |
- <li>Remove package.mask entry</li> |
| 720 |
- <li> |
| 721 |
- Remove the <c><pkg></c> tags referencing this package in the |
| 722 |
- <uri link="::ebuild-writing/misc-files/metadata">metadata.xml</uri> |
| 723 |
- files of other packages. |
| 724 |
- </li> |
| 725 |
- <li>Close open bugs as WONTFIX</li> |
| 726 |
-</ol> |
| 727 |
- |
| 728 |
-<p> |
| 729 |
-Here is a list of commands that will delete <path>dev-util/pmk</path> |
| 730 |
-from the tree: |
| 731 |
-</p> |
| 732 |
- |
| 733 |
-<pre caption="Removing a package from git"> |
| 734 |
-# cd dev-util |
| 735 |
-# git rm -rf pmk |
| 736 |
-# git commit --gpg-sign |
| 737 |
-</pre> |
| 738 |
- |
| 739 |
-<p> |
| 740 |
-An example commit message is shown below: |
| 741 |
-</p> |
| 742 |
- |
| 743 |
-<pre caption="Package removal commit message"> |
| 744 |
-commit e0bbcf8291501dc7de6b4b120d4372061367dd7a |
| 745 |
-Author: Michael Palimaka <kensington@g.o> |
| 746 |
-Date: Fri Jan 29 07:11:01 2016 +1100 |
| 747 |
- |
| 748 |
- dev-util/pmk: remove last-rited package |
| 749 |
- |
| 750 |
- Gentoo-bug: 541522 |
| 751 |
-</pre> |
| 752 |
- |
| 753 |
-</body> |
| 754 |
-</section> |
| 755 |
- |
| 756 |
-<section> |
| 757 |
-<title>Conflicting files</title> |
| 758 |
-<body> |
| 759 |
- |
| 760 |
-<p> |
| 761 |
-When you encounter a package that is trying to install files that are |
| 762 |
-already provided by another package (detectable with |
| 763 |
-<c>FEATURES=collision-protect</c> for example) you have to fix this |
| 764 |
-situation before you can commit the ebuild or, if you encounter this |
| 765 |
-with an existing package, file a bug about that package (see below for |
| 766 |
-a few exceptions). The reason file conflicts are critical is because |
| 767 |
-if "foo" provides the file <path>/usr/bin/example</path> and "bar" is |
| 768 |
-going to overwrite it, and later "bar" is unmerged, Portage will remove |
| 769 |
-<path>/usr/bin/example</path> and it is therefore likely it will break |
| 770 |
-"foo". |
| 771 |
-</p> |
| 772 |
- |
| 773 |
-<p> |
| 774 |
-The most obvious fix is to add a blocking dependency to both packages |
| 775 |
-that want to install that file, so they can't be installed at the same |
| 776 |
-time. But unless there are also other reasons for those packages to |
| 777 |
-block each other you should avoid this if possible and rather fix the |
| 778 |
-package, which could include one or more of the following steps: |
| 779 |
-</p> |
| 780 |
- |
| 781 |
-<ul> |
| 782 |
- <li>Make "foo" (R)DEPEND on "bar" and not install the conflicting |
| 783 |
- file.</li> |
| 784 |
- <li>Remove conflicting files from "foo" in <c>src_install</c> |
| 785 |
- or <c>pkg_preinst</c>.</li> |
| 786 |
- <li>Move conflicting files into a new subpackage and make "foo" and |
| 787 |
- "bar" both (R)DEPEND on that package.</li> |
| 788 |
- <li>Change the location where "foo" or "bar" installs conflicting |
| 789 |
- files.</li> |
| 790 |
-</ul> |
| 791 |
- |
| 792 |
-<p> |
| 793 |
-In some cases conflicting files can't be really fixed or aren't |
| 794 |
-critical, currently known exceptions are Perl module manpages |
| 795 |
-(overwriting the ones from Perl itself) and <c>CONFIG_PROTECT</c>'ed |
| 796 |
-files (which should still be fixed, but aren't critical as Portage |
| 797 |
-won't overwrite them). |
| 798 |
-</p> |
| 799 |
- |
| 800 |
-</body> |
| 801 |
-</section> |
| 802 |
- |
| 803 |
-<section> |
| 804 |
-<title>Homepage unavailable</title> |
| 805 |
-<body> |
| 806 |
- |
| 807 |
-<p> |
| 808 |
-If the <c>HOMEPAGE</c> of your package seems to be unavailable or it |
| 809 |
-never existed at all, please set the HOMEPAGE variable in every ebuild |
| 810 |
-to <uri link="https://wiki.gentoo.org/wiki/No_homepage"> |
| 811 |
-https://wiki.gentoo.org/wiki/No_homepage</uri> |
| 812 |
-</p> |
| 813 |
- |
| 814 |
-</body> |
| 815 |
-</section> |
| 816 |
- |
| 817 |
-</body> |
| 818 |
</chapter> |
| 819 |
+ |
| 820 |
+<include href="maintenance-tasks/"/> |
| 821 |
</guide> |
Archives