diff options
Diffstat (limited to 'ebuild-maintenance/text.xml')
| -rw-r--r-- | ebuild-maintenance/text.xml | 670 |
1 files changed, 5 insertions, 665 deletions
diff --git a/ebuild-maintenance/text.xml b/ebuild-maintenance/text.xml index 0a94d9c..46ab82f 100644 --- a/ebuild-maintenance/text.xml +++ b/ebuild-maintenance/text.xml @@ -5,677 +5,17 @@ <body> <p> -This guide aims to explain common everyday ebuild maintenance -routines, as well as other rarer maintenance routines which -developers may not be familiar with. +This section covers various tasks related to working with ebuilds. </p> - -<section> -<title>Adding a new ebuild</title> -<body> - -<subsection> -<title>What (not) to put in the Gentoo repository</title> -<body> - -<p> -Before writing a new ebuild, check -<uri link="https://bugs.gentoo.org/">bugs.gentoo.org</uri> -to see if an ebuild has already been written for the package, but has not yet -been added to the Gentoo repository. Go to <uri -link="https://bugs.gentoo.org/">bugs.gentoo.org</uri>, choose query and select -Advanced Search; as product select <e>Gentoo Linux</e>, as component select -<e>ebuilds</e>. In the search field put the name of the ebuild and as status -select all possible fields, then submit the query. For you lazy people, click -<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>. -</p> - -<p> -In general, the Gentoo repository should only be used for storing -<path>.ebuild</path> files, as well as any relatively small companion -files, such as patches or sample configuration files. These types of -files should be placed in the <path>/usr/portage/mycat/mypkg/files</path> -directory to keep the main <path>mycat/mypkg</path> directory uncluttered. -Exceptions to this rule are for larger patch files (we recommend this for patches -above 20KB) which should be distributed as tarballs via the -<uri link="::general-concepts/mirrors/#suitable-download-hosts">Gentoo mirror system</uri> -so that people do not waste excessive amounts of bandwidth and hard drive -space. Also, you should not add binary (non-ASCII) files to the -git tree. Also, speaking of merging -changes, any patches you add to Portage should generally <e>not</e> be -compressed. This will allow git to merge changes and correctly inform -developers of conflicts. -</p> - -<p> -Remember, the packages that you commit must be <e>ready</e> <e>out of the -box</e> for end users when committed as stable. Make sure that you have a good -set of default settings that will satisfy the majority of systems and -users that will use your package. If your package is broken, and you are -not sure how to get it to work, check some other distributions that have -done their own versions of the package. You can check -<uri link="http://cvs.mandriva.com/cgi-bin/viewvc.cgi/SPECS/">Mandriva</uri> -or <uri link="http://www.debian.org/distrib/packages">Debian</uri> or -<uri link="http://pkgs.fedoraproject.org/cgit/rpms/">Fedora</uri> for some -examples. -</p> - -<p> -When committing to git, all developers should use <c>repoman commit</c> -instead of <c>git commit</c> to submit their ebuilds. Before committing, -please run <c>repoman full</c> to make sure you didn't forget something. -</p> - -</body> -</subsection> - -<subsection> -<title>Initial Architecture Keywords</title> -<body> -<p> -When adding a new ebuild, you should only include <c>KEYWORDS</c> for -architectures on which you have actually tested the ebuild, confirming -that it works as it should and that <c>USE</c> flags are properly -honoured in the resulting package which would be installed. If -possible, you should give the actual library or application thorough -testing as well, since you would be responsible for any breakages for -your architecture(s). Minimal testing such as checking that the -application starts up without any errors should always be performed. -</p> - -<p> -If you are adding a user-submitted ebuild, do not assume that the -submitter has done testing on various architectures: often, <c>KEYWORDS</c> -are cloned across packages or generated from documentation in the -source packages, which does not signify that the package does indeed -work on those architectures. -</p> - -</body> -</subsection> - -<subsection> -<title>Git Commit Message Format</title> -<body> - -<p> -It is important to format the commit messages properly so that they -communicate the changes to the reader in a clear and concise -way. Additionally, consistency in message format allows for easier -parsing by external tools. The first line of the commit message should -contain a brief summary of the changes, followed by an empty new -line. From the third line onward should be a detailed, multiline -explanation of the changes introduced by the commit. At the very end, -auxiliary information such as the bugs related to the commit, -contributors, and reviewers should be listed using RFC822/git style -tags. The length of the lines in the message should be 70-75 -characters at maximum. -</p> - -<p> -The summary line should start with referencing what is affected by the -change followed by a colon ':' character. Use the rules in the -following list to determine the proper format based on what has -changed, substituting the package, category and eclass names -appropriately: - -<ul> -<li><c>${CATEGORY}/${PN}:</c>Single Package (Note that <c>repoman commit</c> -automatically inserts this for you)</li> -<li><c>${CATEGORY}:</c> Package Category</li> -<li><c>profiles:</c> Profile Directory</li> -<li><c>${ECLASS}.eclass:</c> Eclass Directotry</li> -<li><c>licenses:</c> Licenses Directory</li> -<li><c>metadata:</c> Metadata Directory</li> -</ul> - -For packages where <c>${CATEGORY}/${PN}:</c> is long, the line length -limit can be exceeded, if absolutely necessary, to ensure a more -useful summary line. If a commit affects multiple directories, prepend -the message with which reflects the intention of the change best. If -there are any bugs on Gentoo Bugzilla associated with the commit, id -of the bug can be appended to the summary line using the format -<c>#BUG-ID</c>. If you are modifying keywords, clearly state what -keywords are added/removed. - -<warning> -By default, lines starting with <c>#</c> are considered to be comments -by git and not included in the commit message. Make sure that a new -line does not start with <c>#BUG-ID</c>. Optionally, git can be -configured to use a different character for comments by changing the -<c>commentchar</c> option. -</warning> -</p> - -<p> -For non-trivial commits, the message should contain a detailed -explanation of what the commit intends to change, why it is required, -and how it is accomplished, along with any other supplementary -information. -</p> - -<p> -Finally the commit message should list auxiliary information such as -people who are involved in authoring, suggesting, reviewing and -testing the changes, and revelant bugs. Use RFC822/git style tags as -explained in the -<uri link="https://kernel.org/doc/html/latest/process/submitting-patches.html"> -Linux Kernel patch guideline</uri>. Additionally, the following tags -are optionally used in Gentoo: - -<ul> -<li><c>Bug:</c> Use this to reference bugs <e>without</e> closing them. -The value is a URL to the bug. If multiple bugs need to be referenced, -each one should be listed in a separate <c>Bug</c> tag. If a bug -on Gentoo Bugzilla, or an issue or a pull request on GitHub -is referenced, a reference to the commit will be added -automatically.</li> -<li><c>Closes:</c> Use this to reference bugs and close them -automatically. Alike <c>Bug:</c>, the value is a single URL to the bug, -and multiple tags can be used to close multiple bugs. If a bug on Gentoo -Bugzilla, or an issue or a pull request on a GitHub repository -mirrored by Gentoo is referenced, it will be closed (as fixed) -automatically with reference to the commit.</li> -<li><c>Package-Manager:</c> This is automatically inserted by -<c>repoman commit</c> and it specifies the version of -<pkg>sys-apps/portage</pkg> on the system.</li> -<li><c>RepoMan-Options:</c> This is automatically inserted by -<c>repoman commit</c> and records the options passed to repoman (such -as --force) for the commit.</li> -</ul> -</p> - -<p> -Additionally, some developers prefer referencing bugs on the summary -line using the <c>#nnnnnn</c> form. Developers are free to use either -form, or both simultaneously to combine their advantages. -</p> - -<p> -When committing <uri link="::ebuild-writing/user-submitted">user -contributions</uri>, make sure to credit them in your commit message -with the user's full name and email address. Be aware and respectful -of their privacy: some users prefer to be only known by a -nickname. Take advantage of the tags such as <c>Suggested-By</c> or -<c>Reported-By:</c>when entering such information to the commit -message. -</p> - -<p> -An example commit message is shown below: -</p> - -<pre caption="Example commit message"> -app-misc/foo: version bump to 0.5 - -This also adds a new USE flag 'bar' which controls the -new bar functionality introduced with this version. - -Bug: https://bugs.gentoo.org/00000 -Closes: https://bugs.gentoo.org/00001 -</pre> - </body> -</subsection> - -<subsection> -<title>Git Commit Policy</title> -<body> - -<ul> -<li>Always run <c>repoman scan</c> before you commit.</li> -<li>Please run <c>repoman full</c> before you commit.</li> -<li>Always test that <path>package.mask</path> is okay by doing -<c>emerge --pretend mypkg</c> before you commit and check -that it doesn't contain any conflicts.</li> -<li>Always commit the updated <path>package.mask</path> before -the updated package.</li> -<li>Always do atomic commits; if you commit a package with a new license, -or that is masked, then first commit the revised <path>package.mask</path> and/or license, -then commit the ebuild, patches -and <uri link="::ebuild-writing/misc-files/metadata">metadata.xml</uri> all in <b>one</b> go -.</li> -<note> Although the set of changes in a single git commit is atomic, and -combining <path>package.mask</path>/license changes with ebuild changes in a -single commit wouldn't break atomicity, it is not currently possible to do so -using <c>repoman commit</c>.</note> -<!-- See: https://bugs.gentoo.org/show_bug.cgi?id=390651 --> -</ul> - -</body> -</subsection> - -<subsection> -<title>The files Directory</title> -<body> - -<p> -As noted earlier, under each package subdirectory is -a <path>files/</path> directory. Any patches, configuration files, or -other ancillary files your package might require should be added to -this directory; any files bigger than 20KB-or-so should go to the -mirrors to lower the amount of (unneeded) files our users have to -download. You may want to consider naming patches you create yourself -just to get your package to build with a version-specific name, such -as <path>mypkg-1.0-gentoo.diff</path>, or more -simply, <path>1.0-gentoo.diff</path>. Also note that the -<path>gentoo</path> extension informs people that this patch was created -by us, the Gentoo Linux developers, rather than having been grabbed from a -mailing list or somewhere else. Again, you should not compress these -patches. -</p> - -<p> -Consider prefixing or suffixing (such as <path>mypkg-1.0</path>) every file -you put into the <path>files/</path> directory, so that the files used for -each individual version on an ebuild are distinguishable from one another, and -so that the changes between different revisions are visible. This is generally -a really good idea :). You may want to use a different suffix if you wish to -convey more meaning with the patch name. -</p> - -<p> -If you have many files that should go into the <path>files/</path> directory, -consider creating subdirectories such as <path>files/1.0/</path> and putting the -relevant files in the appropriate subdirectory. If you use this method, -you do not need to add version information to the names of the files, -which is often more convenient. -</p> - -</body> -</subsection> - -</body> -</section> <section> -<title>Touching other developers ebuilds</title> +<title>Contents</title> <body> -<p> -Usually you don't just change other developers ebuilds without -permission unless you know that developer does not mind or if you are -part of the project involved in maintenance (this information can -typically be found in metadata.xml). Start with filing a bug or trying -to catch them on IRC or via email. Sometimes you cannot reach them, or -there is no response to your bug. It's a good idea to consult other -developers on how to handle the situation, especially if it's a -critical issue that needs to be handled ASAP. Otherwise a soft limit -of 2 to 4 weeks depending on the severity of the bug is an acceptable -time frame before you go ahead and fix it yourself. -</p> -<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> - -<p> -Respect developers' coding preferences. Unnecessarily changing the -syntax of an ebuild can cause complications for others. Syntax changes -should only be done if there is a real benefit, such as faster -compilation, improved information for the end user, or compliance with -Gentoo policies. -</p> - +<contentsTree/> </body> </section> - -<section> -<title>Stabilizing ebuilds</title> -<body> - -<p> -Only architecture maintainers for a given architecture should mark packages as -stable on that architecture. The maintainer of the package should always be -contacted just in case there are reasons not to do so. The exception to this -is if you are part of an architecture team, in which case you may mark the -package stable for that architecture. If you are not part of an architecture -team, you should consult the guidelines below; if the architecture you are -looking for is not listed then please consult the relevant lead. -</p> - -<p> -You should <e>never</e> stabilize packages on -architectures for which you cannot test and instead you should file a bug to -the relevant architecture team, such as <mail link="sparc@gentoo.org"> -sparc@gentoo.org</mail> asking them to stabilize the -ebuild. Alternatively, you may be able to find Gentoo developers on -IRC who could help you with your request. -</p> - -<p> -It is best to not use <mail link="arch-maintainers@gentoo.org"> -arch-maintainers@gentoo.org</mail>, adding architecture teams onto a -bug's CC list individually instead. That way teams can remove -themselves from the list when they are done, giving a clear indication -of which teams still have to stabilize a package. -</p> - -</body> -</section> - -<section> -<title>Stabilization rules</title> -<body> - -<p> -SPARC: You must have prior permission from the arch lead. Usually we expect -you to be on the sparc alias for QA reasons, although other arrangements -can be made if you will only be working with a small group of packages. -</p> - -<p> -ALPHA: Maintainers may keyword their own packages but are reminded to inform -the Alpha team if they can help out with testing and keywording packages so -the team can keep an eye out for possible keywording mistakes. -</p> - -<p> -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. -</p> -<p> -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. -</p> -</body> -</section> - -<section> -<title>Upgrading ebuilds</title> -<body> - -<p> -New ebuilds should rarely go in with "<c>arch</c>" keywords and even if they do -not, the package <e>must</e> be tested on any architectures listed in the -<c>KEYWORDS</c> variable of the new ebuild. -</p> - -<p> -Exceptions to the no "<c>arch</c>" rule are major bug fixes, or -security fixes. If the previous version of the ebuild -contains <c>KEYWORDS</c> which you cannot test for, you should -downgrade them: turn any "<c>arch</c>" keyword to "<c>~arch</c>". If you -think that your package may not work at all even on "<c>~arch</c>" -then it is best to leave the keyword out and request testing from the -relevant team: if you are to do this, you must file a bug to the team -in question. -</p> - -<p> -If a new version introduces new dependencies which are not available -on some architectures, then you should file a bug or ask on IRC before -you upgrade the package. If you really need to get the ebuild added in -a hurry, for example, for a security fix, then you should drop -any <c>KEYWORDS</c> which are causing problems and CC the relevant -architectures on the bug - you should file a new bug to the -architecture in question regarding this if no bug is already -available. -</p> - -<p> -If there are no new dependencies, do not remove keywords if your -commit fails with repoman - please try a full <c>git pull</c> and if -you still have problems, then commit with <c>repoman -I</c> and file a -bug to the broken architecture, noting it in your git commit message. -</p> - -<warning> -When committing, make sure that you reference any bugs in the -commit message. Failing to do so is considered -to be in very poor taste and may result in disciplinary action. -</warning> - -</body> -</section> - -<section> -<title>Moving a package</title> -<body> - -<p> -Moving a package in the tree requires several operations. Firstly, -the package directory needs to be moved to the correct category -using <c>git mv</c>. After this, a new entry needs to be added to -the latest file in <path>profiles/updates/</path> in the -following format: -</p> - -<pre caption="Adding an entry to updates"> -move old-category/package-name new-category/package-name -</pre> - -<p> -Following the update entry, ebuilds that have a -<uri link="::general-concepts/dependencies">dependency</uri> -to this package (in other words, the reverse dependencies of -the package to be moved) need to be updated properly. -</p> - -<p> -Next is checking the files under <path>profiles/</path> such as -<path>profiles/package.mask</path> and update them to reflect the ebuild -move. Various eclasses automatically provide some of the dependencies upon -inherit, so the files under <path>eclass/</path> should be checked and updated -properly. If the package metadata.xml has tags with <c>restrict</c> -attribute, they should be updated to reflect the move. The -metadata.xml for various packages may contain references to the -package being moved using the <c><pkg></c> tag which need to be -updated accordingly as well. Lastly, the titles of the open bugs -related to the package should be updated. -</p> - -<p> -Here is an example where the package -<path>net-misc/fwbuilder</path> is transparently moved to -<path>net-firewall/fwbuilder</path>: -</p> - -<ol> - <li>Issue <c>git mv net-misc/fwbuilder net-firewall/fwbuilder</c></li> - <li> - <p> - Add the following entry to the latest file in - <path>profile/updates/</path>: - </p> - <p><c>move net-misc/fwbuilder net-firewall/fwbuilder</c></p> - </li> - <li>Update the reverse dependencies of the package</li> - <li> - Update <path>profiles/package.mask</path> and other related files under - <path>profiles/</path> - </li> - <li>Check the eclasses that may be referencing the package</li> - <li> - Update all the - <uri link="::ebuild-writing/misc-files/metadata">metadata.xml</uri> - files which contain a reference to this package using the - <c><pkg></c> tag or the <c>restrict</c> attribute. - </li> - <li> - Stage all the changed files using <c>git add</c>. For example: <c>git add - profiles/package.mask</c> - </li> - <li> - Commit all the changes in one commit using: <c>git commit --gpg-sign</c> - </li> - <li> - Update any <uri link="::general-concepts/news">news items</uri> - referencing the package in a <c>Display-If-Installed</c> header - or in the item's body (and increment their <c>Revision</c>). - </li> - <li>Update any open bugs related to the package</li> -</ol> - -<p> -It is very important to commit all the changes in a single commit to ensure -that no breakage occurs. The commit message should follow a format similar -to the following: -</p> - -<pre> -commit d391643289097344a0b18ab2665bb26198a0e3a1 -Author: Guilherme Amadio <amadio@gentoo.org> -Date: Tue Nov 3 20:26:52 2015 +0100 - - media-fonts/nanumfont: renamed to media-fonts/nanum -</pre> - -</body> -</section> - -<section> -<title>Changing ebuild's SLOT</title> -<body> -<p> -The process for changing the ebuild's SLOT is very similar to the previous process. -Besides changing the SLOT in the ebuild file, you also need to create a new entry -in <path>profiles/updates/</path> in the Gentoo repository in the following format: -</p> - -<pre caption="Adding an entry to updates"> -slotmove app-text/gtkspell 0 2 -</pre> - -<p>Make sure that you have fixed all the reverse dependencies and that you have -updated every file in <path>profiles/</path> directory that happens to contain an -entry which may be affected by your change. -</p> - -</body> -</section> - -<section> -<title>Removing ebuilds</title> -<body> - -<p> -When removing an ebuild make sure that no dependencies in Portage are broken -due to the removal - additionally, your git commit message should explain -clearly why the ebuild is being removed from the git repository. -</p> - -<p> -If you need to remove ebuilds, make sure you do not accidentally remove -the newest/only stable ebuild for any architecture. If you would like to -get a newer version marked stable, then please file a bug or ask on IRC. -</p> - -<p> -You should also not cause an unnecessary downgrade for any "<c>~arch</c>" -when removing ebuilds - instead, it is best to get the newest version -marked "<c>~arch</c>" first and then remove redundant versions of the ebuild. -</p> - -</body> -</section> - -<section> -<title>Removing a package</title> -<body> - -<p> -When removing packages follow these steps: -</p> - -<ol> - <li>Make sure that no dependencies in Portage are broken due to the removal</li> - <li>Send last rites to gentoo-dev-announce and gentoo-dev</li> - <li>Mask the package</li> - <li>Wait 30 days (or more)</li> - <li>Remove from the git tree unless the reason for removal has been fixed</li> - <li>Remove package.mask entry</li> - <li> - Remove the <c><pkg></c> tags referencing this package in the - <uri link="::ebuild-writing/misc-files/metadata">metadata.xml</uri> - files of other packages. - </li> - <li>Close open bugs as WONTFIX</li> -</ol> - -<p> -Here is a list of commands that will delete <path>dev-util/pmk</path> -from the tree: -</p> - -<pre caption="Removing a package from git"> -# cd dev-util -# git rm -rf pmk -# git commit --gpg-sign -</pre> - -<p> -An example commit message is shown below: -</p> - -<pre caption="Package removal commit message"> -commit e0bbcf8291501dc7de6b4b120d4372061367dd7a -Author: Michael Palimaka <kensington@gentoo.org> -Date: Fri Jan 29 07:11:01 2016 +1100 - - dev-util/pmk: remove last-rited package - - Gentoo-bug: 541522 -</pre> - -</body> -</section> - -<section> -<title>Conflicting files</title> -<body> - -<p> -When you encounter a package that is trying to install files that are -already provided by another package (detectable with -<c>FEATURES=collision-protect</c> for example) you have to fix this -situation before you can commit the ebuild or, if you encounter this -with an existing package, file a bug about that package (see below for -a few exceptions). The reason file conflicts are critical is because -if "foo" provides the file <path>/usr/bin/example</path> and "bar" is -going to overwrite it, and later "bar" is unmerged, Portage will remove -<path>/usr/bin/example</path> and it is therefore likely it will break -"foo". -</p> - -<p> -The most obvious fix is to add a blocking dependency to both packages -that want to install that file, so they can't be installed at the same -time. But unless there are also other reasons for those packages to -block each other you should avoid this if possible and rather fix the -package, which could include one or more of the following steps: -</p> - -<ul> - <li>Make "foo" (R)DEPEND on "bar" and not install the conflicting - file.</li> - <li>Remove conflicting files from "foo" in <c>src_install</c> - or <c>pkg_preinst</c>.</li> - <li>Move conflicting files into a new subpackage and make "foo" and - "bar" both (R)DEPEND on that package.</li> - <li>Change the location where "foo" or "bar" installs conflicting - files.</li> -</ul> - -<p> -In some cases conflicting files can't be really fixed or aren't -critical, currently known exceptions are Perl module manpages -(overwriting the ones from Perl itself) and <c>CONFIG_PROTECT</c>'ed -files (which should still be fixed, but aren't critical as Portage -won't overwrite them). -</p> - -</body> -</section> - -<section> -<title>Homepage unavailable</title> -<body> - -<p> -If the <c>HOMEPAGE</c> of your package seems to be unavailable or it -never existed at all, please set the HOMEPAGE variable in every ebuild -to <uri link="https://wiki.gentoo.org/wiki/No_homepage"> -https://wiki.gentoo.org/wiki/No_homepage</uri> -</p> - -</body> -</section> - -</body> </chapter> + +<include href="maintenance-tasks/"/> </guide> |