commit: d2e77eb8f1abe200a4c0ede569fa169c08205545
Author: Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sat Oct 14 09:40:48 2017 +0000
Commit: Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed Jan 3 01:20:19 2018 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=d2e77eb8
Convert 'Ebuild Maintenance' into a section
The committer has reflowed some of the lines past 80 characters.
.../{ => maintenance-tasks}/text.xml | 62 +-
ebuild-maintenance/text.xml | 670 +--------------------
2 files changed, 44 insertions(+), 688 deletions(-)
diff --git a/ebuild-maintenance/text.xml
b/ebuild-maintenance/maintenance-tasks/text.xml
similarity index 92%
copy from ebuild-maintenance/text.xml
copy to ebuild-maintenance/maintenance-tasks/text.xml
index 0a94d9c..ba401ca 100644
--- a/ebuild-maintenance/text.xml
+++ b/ebuild-maintenance/maintenance-tasks/text.xml
@@ -1,7 +1,7 @@
<?xml version="1.0"?>
-<guide self="ebuild-maintenance/">
+<guide self="ebuild-maintenance/maintenance-tasks/">
<chapter>
-<title>Ebuild Maintenance</title>
+<title>Maintenance Tasks</title>
<body>
<p>
@@ -33,17 +33,18 @@ select all possible fields, then submit the query. For you
lazy people, click
<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
+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>
@@ -303,7 +304,12 @@ 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>
+<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
@@ -367,10 +373,16 @@ 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.
+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.
+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>
@@ -522,18 +534,20 @@ Date: Tue Nov 3 20:26:52 2015 +0100
<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:
+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>
+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>
@@ -573,7 +587,9 @@ When removing packages follow these steps:
</p>
<ol>
- <li>Make sure that no dependencies in Portage are broken due to the
removal</li>
+ <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>
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="sp...@gentoo.org">
-sp...@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-maintain...@gentoo.org">
-arch-maintain...@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 <ama...@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 <kensing...@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>
