chiark / gitweb /
Commit DEP1, that rewrites the whole NMU section
authorlucas <lucas@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Tue, 26 Aug 2008 08:37:40 +0000 (08:37 +0000)
committerlucas <lucas@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Tue, 26 Aug 2008 08:37:40 +0000 (08:37 +0000)
This doesn't mean that I'm not open to changes to this, but I think that we
have discussed this enough now, and I'd like the svn repository to reflect the
current state of the discussion (rather than my local copy)

git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@5353 313b444b-1b9f-4f58-a734-7bb04f332e8d

common.ent
pkgs.dbk

index b3fe901..3249312 100644 (file)
@@ -85,6 +85,9 @@
 
 <!ENTITY url-incoming "http://incoming.debian.org/">
 <!ENTITY url-testing-maint "http://www.debian.org/devel/testing">
+<!ENTITY url-low-threshold-nmu "http://wiki.debian.org/LowThresholdNmu">
+<!ENTITY url-orphaned-not-qa "http://qa.debian.org/orphaned.html">
+
 <!-- deprecated -->
 
 <!ENTITY url-mentors "http://people.debian.org/~mpalmer/debian-mentors_FAQ.html">
index 8f1f36b..25c58a8 100644 (file)
--- a/pkgs.dbk
+++ b/pkgs.dbk
@@ -1829,325 +1829,315 @@ role="package">ftp.debian.org</systemitem>
 <section id="nmu">
 <title>Non-Maintainer Uploads (NMUs)</title>
 <para>
-Under certain circumstances it is necessary for someone other than the official
-package maintainer to make a release of a package.  This is called a
-non-maintainer upload, or NMU.
-</para>
-<para>
-This section handles only source NMUs, i.e.  NMUs which upload a new version of
-the package.  For binary-only NMUs by porters or QA members, please see <xref
-linkend="binary-only-nmu"/> .  If a buildd builds and uploads a package, that
-too is strictly speaking a binary NMU.  See <xref linkend="wanna-build"/> for
-some more information.
-</para>
-<para>
-The main reason why NMUs are done is when a developer needs to fix another
-developer's package in order to address serious problems or crippling bugs or
-when the package maintainer is unable to release a fix in a timely fashion.
-</para>
-<para>
-First and foremost, it is critical that NMU patches to source should be as
-non-disruptive as possible.  Do not do housekeeping tasks, do not change the
-name of modules or files, do not move directories; in general, do not fix
-things which are not broken.  Keep the patch as small as possible.  If things
-bother you aesthetically, talk to the Debian maintainer, talk to the upstream
-maintainer, or submit a bug.  However, aesthetic changes must
-<emphasis>not</emphasis> be made in a non-maintainer upload.
-</para>
-<para>
-And please remember the Hippocratic Oath: Above all, do no harm.  It is better
-to leave a package with an open grave bug than applying a non-functional patch,
-or one that hides the bug instead of resolving it.
+Every package has one or more maintainers. Normally, these are the people who
+work on and upload new versions of the package. In some situations, it is
+useful that other developers can upload a new version as well, for example if
+they want to fix a bug in a package they don't maintain, when the maintainer
+needs help to respond to issues.  Such uploads are called
+<emphasis>Non-Maintainer Uploads (NMU)</emphasis>.
 </para>
+
 <section id="nmu-guidelines">
-<title>How to do a NMU</title>
-<para>
-NMUs which fix important, serious or higher severity bugs are encouraged and
-accepted.  You should endeavor to reach the current maintainer of the package;
-they might be just about to upload a fix for the problem, or have a better
-solution.
-</para>
-<para>
-NMUs should be made to assist a package's maintainer in resolving bugs.
-Maintainers should be thankful for that help, and NMUers should respect the
-decisions of maintainers, and try to personally help the maintainer by their
-work.
-</para>
+<title>When and how to do an NMU</title>
+
 <para>
-A NMU should follow all conventions, written down in this section.  For an
-upload to <literal>testing</literal> or <literal>unstable</literal>, this
-order of steps is recommended:
+Before doing an NMU, consider the following questions:
 </para>
 <itemizedlist>
 <listitem>
 <para>
-Make sure that the package's bugs that the NMU is meant to address are all
-filed in the Debian Bug Tracking System (BTS).  If they are not, submit them
-immediately.
+Does your NMU really fix bugs? Fixing cosmetic issues or changing the
+packaging style in NMUs is discouraged.
 </para>
 </listitem>
 <listitem>
 <para>
-Wait a few days for the response from the maintainer.  If you don't get any
-response, you may want to help them by sending the patch that fixes the bug.
-Don't forget to tag the bug with the patch keyword.
+Did you give enough time to the maintainer? When was the bug reported to the
+BTS? Being busy for a week or two isn't unusual.  Is the bug so severe that it
+needs to be fixed right now, or can it wait a few more days?
 </para>
 </listitem>
 <listitem>
 <para>
-Wait a few more days.  If you still haven't got an answer from the maintainer,
-send them a mail announcing your intent to NMU the package.  Prepare an NMU as
-described in this section, and test it carefully on your machine (cf.  <xref
-linkend="sanitycheck"/> ).  Double check that your patch doesn't have any
-unexpected side effects.  Make sure your patch is as small and as
-non-disruptive as it can be.
+How confident are you about your changes? Please remember the Hippocratic Oath:
+"Above all, do no harm." It is better to leave a package with an open grave bug
+than applying a non-functional patch, or one that hides the bug instead of
+resolving it. If you are not 100% sure of what you did, it might be a good idea
+to seek advice from others. Remember that if you break something in your NMU,
+many people will be very unhappy about it.
 </para>
 </listitem>
 <listitem>
 <para>
-Upload your package to incoming in <filename>DELAYED/7-day</filename> (cf.
-<xref linkend="delayed-incoming"/> ), send the final patch to the maintainer
-via the BTS, and explain to them that they have 7 days to react if they want to
-cancel the NMU.
+Have you clearly expressed your intention to NMU, at least in the BTS?
+It is also a good idea to try to contact the
+maintainer by other means (private email, IRC).
 </para>
 </listitem>
 <listitem>
 <para>
-Follow what happens, you're responsible for any bug that you introduced with
-your NMU.  You should probably use <xref linkend="pkg-tracking-system"/> (PTS)
-to stay informed of the state of the package after your NMU.
+If the maintainer is usually active and responsive, have you tried to contact
+him? In general it should be considered preferable that a maintainer takes care
+of an issue himself and that he is given the chance to review and correct your
+patch, because he can be expected to be more aware of potential issues which an
+NMUer might miss. It is often a better use of everyone's time if the maintainer
+is given an opportunity to upload a fix on their own.
 </para>
 </listitem>
 </itemizedlist>
 <para>
-At times, the release manager or an organized group of developers can announce
-a certain period of time in which the NMU rules are relaxed.  This usually
-involves shortening the period during which one is to wait before uploading the
-fixes, and shortening the DELAYED period.  It is important to notice that even
-in these so-called bug squashing party times, the NMU'er has to file bugs and
-contact the developer first, and act later.  Please see <xref
-linkend="qa-bsp"/> for details.
+When doing an NMU, you must first make sure that your intention to NMU is
+clear.  Then, you must send a patch with the differences between the
+current package and your proposed NMU to the BTS. The
+<literal>nmudiff</literal> script in the <literal>devscripts</literal> package
+might be helpful.
 </para>
 <para>
-For the <literal>testing</literal> distribution, the rules may be changed by
-the release managers.  Please take additional care, and acknowledge that the 
-usual way for a package to enter <literal>testing</literal> is through 
-<literal>unstable</literal>.
+While preparing the patch, you should better be aware of any package-specific
+practices that the maintainer might be using. Taking them into account reduces
+the burden of getting your changes integrated back in the normal package
+workflow and thus increases the possibilities that that will happen. A good
+place where to look for for possible package-specific practices is
+<ulink url="&url-debian-policy;ch-source.html#s-readmesource"><literal>debian/README.source</literal></ulink>.
 </para>
 <para>
-For the stable distribution, please take extra care.  Of course, the release
-managers may also change the rules here.  Please verify before you upload that
-all your changes are OK for inclusion into the next stable release by the
-release manager.
+Unless you have an excellent reason not to do so, you must then give some time
+to the maintainer to react (for example, by uploading to the
+<literal>DELAYED</literal> queue).  Here are some recommended values to use for delays:
 </para>
+<itemizedlist>
+<listitem>
 <para>
-When a security bug is detected, the security team may do an NMU, using their
-own rules.  Please refer to <xref linkend="bug-security"/> for more
-information.
+Upload fixing only release-critical bugs older than 7 days: 2 days
 </para>
+</listitem>
+<listitem>
 <para>
-For the differences for Porters NMUs, please see <xref
-linkend="source-nmu-when-porter"/> .
+Upload fixing only release-critical and important bugs: 5 days
 </para>
+</listitem>
+<listitem>
 <para>
-Of course, it is always possible to agree on special rules with a maintainer
-(like the maintainer asking please upload this fix directly for me, and no diff
-required).
+Other NMUs: 10 days
 </para>
-</section>
+</listitem>
+</itemizedlist>
 
-<section id="nmu-version">
-<title>NMU version numbering</title>
 <para>
-Whenever you have made a change to a package, no matter how trivial, the
-version number needs to change.  This enables our packing system to function.
+Those delays are only examples. In some cases, such as uploads fixing security
+issues, or fixes for trivial bugs that blocking a transition, it is desirable
+that the fixed package reaches <literal>unstable</literal> sooner.
 </para>
+
 <para>
-If you are doing a non-maintainer upload (NMU), you should add a new minor
-version number to the <replaceable>debian-revision</replaceable> part of the
-version number (the portion after the last hyphen).  This extra minor number
-will start at `1'.  For example, consider the package `foo', which is at
-version 1.1-3.  In the archive, the source package control file would be
-<filename>foo_1.1-3.dsc</filename>.  The upstream version is `1.1' and the
-Debian revision is `3'.  The next NMU would add a new minor number `.1' to the
-Debian revision; the new source control file would be
-<filename>foo_1.1-3.1.dsc</filename>.
-</para>
-<para>
-The Debian revision minor number is needed to avoid stealing one of the package
-maintainer's version numbers, which might disrupt their work.  It also has the
-benefit of making it visually clear that a package in the archive was not made
-by the official maintainer.
+Sometimes, release managers decide to allow NMUs with shorter delays for a
+subset of bugs (e.g release-critical bugs older than 7 days). Also, some
+maintainers list themselves in the <ulink url="&url-low-threshold-nmu;">Low
+Threshold NMU list</ulink>, and accept that NMUs are uploaded without delay. But
+even in those cases, it's still a good idea to give the maintainer a few days
+to react before you upload, especially if the patch wasn't available in the BTS
+before, or if you know that the maintainer is generally active.
 </para>
+
 <para>
-If there is no <replaceable>debian-revision</replaceable> component in the
-version number then one should be created, starting at `0.1' (but in case of a
-debian native package still upload it as native package).  If it is absolutely
-necessary for someone other than the usual maintainer to make a release based
-on a new upstream version then the person making the release should start with
-the <replaceable>debian-revision</replaceable> value `0.1'.  The usual
-maintainer of a package should start their
-<replaceable>debian-revision</replaceable> numbering at `1'.
+After you upload an NMU, you are responsible for the possible problems that you
+might have introduced. You must keep an eye on the package (subscribing to the
+package on the PTS is a good way to achieve this).
 </para>
+
 <para>
-If you upload a package to <literal>testing</literal> or <literal>stable
-</literal>, sometimes, you need to fork the version number tree.  For this,
-version numbers like 1.1-3sarge0.1 could be used.
+This is not a license to perform NMUs thoughtlessly.  If you NMU when it is
+clear that the maintainers are active and would have acknowledged a patch in a
+timely manner, or if you ignore the recommendations of this document, your
+upload might be a cause of conflict with the maintainer.
+You should always be prepared to
+defend the wisdom of any NMU you perform on its own merits.
 </para>
 </section>
 
 <section id="nmu-changelog">
-<title>Source NMUs must have a new changelog entry</title>
+<title>NMUs and debian/changelog</title>
 <para>
-Anyone who is doing a source NMU must create a changelog entry, describing
-which bugs are fixed by the NMU, and generally why the NMU was required and
-what it fixed.  The changelog entry will have the email address of the person
-who uploaded it in the log entry and the NMU version number in it.
-</para>
-<para>
-By convention, source NMU changelog entries start with the line
+Just like any other (source) upload, NMUs must add an entry to
+<literal>debian/changelog</literal>, telling what has changed with this
+upload.  The first line of this entry must explicitely mention that this upload is an NMU, e.g.:
 </para>
 <screen>
-  * Non-maintainer upload
+  * Non-maintainer upload.
 </screen>
-</section>
 
-<section id="nmu-patch">
-<title>Source NMUs and the Bug Tracking System</title>
 <para>
-Maintainers other than the official package maintainer should make as few
-changes to the package as possible, and they should always send a patch as a
-unified context diff (<literal>diff -u</literal>) detailing their changes to
-the Bug Tracking System.
+The version must be the version of the last maintainer upload, plus
+<literal>+nmu<replaceable>X</replaceable></literal>, where
+<replaceable>X</replaceable> is a counter starting at <literal>1</literal>.  If
+the last upload was also an NMU, the counter should be increased.  For example,
+if the current version is <literal>1.5-1</literal>, then an NMU would get
+version <literal>1.5-1+nmu1</literal>.  If the current version is
+<literal>1.5+nmu3</literal> (a native package which has already been NMUed), the
+NMU would get version <literal>1.5+nmu4</literal>.  If a new upstream version
+is packaged in the NMU, the debian revision is set to <literal>0</literal>, for
+example <literal>1.6-0+nmu1</literal>.
+</para>
+
+<para>
+A special versioning scheme is needed to avoid disrupting the maintainer's
+work, since using an integer for the Debian revision will potentially
+conflict with a maintainer upload already in preparation at the time of an
+NMU, or even one sitting in the ftp NEW queue.
+It also has the
+benefit of making it visually clear that a package in the archive was not made
+by the official maintainer.
 </para>
+
 <para>
-What if you are simply recompiling the package?  If you just need to recompile
-it for a single architecture, then you may do a binary-only NMU as described in
-<xref linkend="binary-only-nmu"/> which doesn't require any patch to be sent.
-If you want the package to be recompiled for all architectures, then you do a
-source NMU as usual and you will have to send a patch.
+If you upload a package to testing or stable, you sometimes need to "fork" the
+version number tree. This is the case for security uploads, for example.  For
+this, a version of the form
+<literal>+deb<replaceable>XY</replaceable>u<replaceable>Z</replaceable></literal>
+should be used, where <replaceable>X</replaceable> and
+<replaceable>Y</replaceable> are the major and minor release numbers, and
+<replaceable>Z</replaceable> is a counter starting at <literal>1</literal>.
+When the release number is not yet known (often the case for
+<literal>testing</literal>, at the beginning of release cycles), the lower
+release number higher than the last stable release number must be used.  For
+example, while Etch (Debian 4.0) is stable, a security NMU to stable for a
+package at version <literal>1.5-3</literal> would have version
+<literal>1.5-3+deb40u1</literal>, whereas a security NMU to Lenny would get
+version <literal>1.5-3+deb50u1</literal>. After the release of Lenny, security
+uploads to the <literal>testing</literal> distribution will be versioned
+<literal>+deb51uZ</literal>, until it is known whether that release will be
+Debian 5.1 or Debian 6.0 (if that becomes the case, uploads will be versioned
+as <literal>+deb60uZ</literal>.
 </para>
+</section>
+
+<section id="nmu-delayed">
+<title>Using the <literal>DELAYED/</literal> queue</title>
+
 <para>
-Bugs fixed by source NMUs used to be tagged fixed instead of closed, but since
-version tracking is in place, such bugs are now also closed with the NMU
-version.
+Having to wait for a response after you request permission to NMU is
+inefficient, because it costs the NMUer a context switch to come back to the
+issue.
+The <literal>DELAYED</literal> queue (see <xref linkend="delayed-incoming"/>)
+allows the developer doing the NMU to perform all the necessary tasks at the
+same time. For instance, instead of telling the maintainer that you will
+upload the updated
+package in 7 days, you should upload the package to
+<literal>DELAYED/7</literal> and tell the maintainer that he has 7 days to
+react.  During this time, the maintainer can ask you to delay the upload some
+more, or cancel your upload.
 </para>
+
 <para>
-Also, after doing an NMU, you have to send the information to the existing bugs
-that are fixed by your NMU, including the unified diff.  Historically, it was
-custom to open a new bug and include a patch showing all the changes you have
-made.  The normal maintainer will either apply the patch or employ an alternate
-method of fixing the problem.  Sometimes bugs are fixed independently upstream,
-which is another good reason to back out an NMU's patch.  If the maintainer
-decides not to apply the NMU's patch but to release a new version, the
-maintainer needs to ensure that the new upstream version really fixes each
-problem that was fixed in the non-maintainer release.
+The <literal>DELAYED</literal> queue should not be used to put additional
+pressure on the maintainer. In particular, it's important that you are
+available to cancel or delay the upload before the delay expires since the
+maintainer cannot cancel the upload himself.
 </para>
+
 <para>
-In addition, the normal maintainer should <emphasis>always</emphasis> retain
-the entry in the changelog file documenting the non-maintainer upload -- and of
-course, also keep the changes.  If you revert some of the changes, please
-reopen the relevant bug reports.
+If you make an NMU to <literal>DELAYED</literal> and the maintainer updates
+his package before the delay expires, your upload will be rejected because a
+newer version is already available in the archive.
+Ideally, the maintainer will take care to include your proposed changes (or
+at least a solution for the problems they address) in that upload.
 </para>
+
 </section>
 
-<section id="nmu-build">
-<title>Building source NMUs</title>
+<section id="nmu-maintainer">
+<title>NMUs from the maintainer's point of view</title>
+
 <para>
-Source NMU packages are built normally.  Pick a distribution using the same
-rules as found in <xref linkend="distribution"/> , follow the other
-instructions in <xref linkend="upload"/> .
+When someone NMUs your package, this means they want to help you to keep it in
+good shape.  This gives users fixed packages faster.  You
+can consider asking the NMUer to become a co-maintainer of the package.
+Receiving an NMU on a package is not a bad
+thing; it just means that the package is interesting enough for other people to
+work on it.
 </para>
+
 <para>
-Make sure you do <emphasis>not</emphasis> change the value of the maintainer in
-the <filename>debian/control</filename> file.  Your name as given in the NMU
-entry of the <filename>debian/changelog</filename> file will be used for
-signing the changes file.
+To acknowledge an NMU, include its changes and changelog entry in your next
+maintainer upload.  If you do not acknowledge the NMU by including the
+NMU changelog entry in your changelog, the bugs will remain closed in the
+BTS but will be listed as affecting your maintainer version of the package.
 </para>
+
 </section>
 
-<section id="ack-nmu">
-<title>Acknowledging an NMU</title>
+<section id="nmu-binnmu">
+<title>Source NMUs vs Binary-only NMUs (binNMUs)</title>
+
 <para>
-If one of your packages has been NMU'ed, you have to incorporate the changes in
-your copy of the sources.  This is easy, you just have to apply the patch that
-has been sent to you.  Once this is done, you have to close the bugs that have
-been tagged fixed by the NMU.  The easiest way is to use the
-<literal>-v</literal> option of <command>dpkg-buildpackage</command>, as this
-allows you to include just all changes since your last maintainer upload.
-Alternatively, you can close them manually by sending the required mails to the
-BTS or by adding the required <literal>closes: #nnnn</literal> in the changelog
-entry of your next upload.
+The full name of an NMU is <emphasis>source NMU</emphasis>.  There is also
+another type, namely the <emphasis>binary-only NMU</emphasis>, or
+<emphasis>binNMU</emphasis>.  A binNMU is also a package upload by someone
+other than the package's maintainer.  However, it is a binary-only upload.
 </para>
+
 <para>
-In any case, you should not be upset by the NMU.  An NMU is not a personal
-attack against the maintainer.  It is a proof that someone cares enough about
-the package that they were willing to help you in your work, so you should be
-thankful.  You may also want to ask them if they would be interested in helping
-you on a more frequent basis as co-maintainer or backup maintainer (see <xref
-linkend="collaborative-maint"/> ).
+When a library (or other dependency) is updated, the packages using it may need
+to be rebuilt.  Since no changes to the source are needed, the same source
+package is used.
 </para>
-</section>
 
-<section id="nmu-vs-qa">
-<title>NMU vs QA uploads</title>
 <para>
-Unless you know the maintainer is still active, it is wise to check the package
-to see if it has been orphaned.  The current list of orphaned packages which
-haven't had their maintainer set correctly is available at <ulink
-url="&url-debian-qa-orphaned;"></ulink>.  If you perform an NMU on an
-improperly orphaned package, please set the maintainer to <literal>Debian QA Group
-&lt;packages@qa.debian.org&gt;</literal>.
+BinNMUs are usually triggered on the buildds by wanna-build.
+An entry is added to debian/changelog,
+explaining why the upload was needed and increasing the version number as
+described in <xref linkend="binary-only-nmu"/>.
+This entry should not be included in the next upload.
 </para>
-</section>
 
-<section id="nmu-who">
-<title>Who can do an NMU</title>
 <para>
-Only official, registered Debian Developers can do binary or source NMUs.  A
-Debian Developer is someone who has their key in the Debian key ring.
-Non-developers, however, are encouraged to download the source package and
-start hacking on it to fix problems; however, rather than doing an NMU, they
-should just submit worthwhile patches to the Bug Tracking System.  Maintainers
-almost always appreciate quality patches and bug reports.
+Buildds upload packages for their architecture to the archive as binary-only
+uploads.  Strictly speaking, these are binNMUs.  However, they are not normally
+called NMU, and they don't add an entry to debian/changelog.
 </para>
+
 </section>
 
-<section id="nmu-terms">
-<title>Terminology</title>
+<section id="nmu-qa-upload">
+<title>NMUs vs QA uploads</title>
+
 <para>
-There are two new terms used throughout this section: ``binary-only NMU'' and
-``source NMU''.  These terms are used with specific technical meaning
-throughout this document.  Both binary-only and source NMUs are similar, since
-they involve an upload of a package by a developer who is not the official
-maintainer of that package.  That is why it's a
-<literal>non-maintainer</literal> upload.
+NMUs are uploads of packages by somebody else than their assigned maintainer.
+There is
+another type of upload where the uploaded package is not yours: QA uploads. QA
+uploads are uploads of orphaned packages.
 </para>
+
 <para>
-A source NMU is an upload of a package by a developer who is not the official
-maintainer, for the purposes of fixing a bug in the package.  Source NMUs
-always involves changes to the source (even if it is just a change to
-<filename>debian/changelog</filename>).  This can be either a change to the
-upstream source, or a change to the Debian bits of the source.  Note, however,
-that source NMUs may also include architecture-dependent packages, as well as
-an updated Debian diff.
+QA uploads are very much like normal maintainer uploads: they may fix anything,
+even minor issues; the version numbering is normal, and there is no need to use
+a delayed upload.  The difference is that you are not listed as the Maintainer
+or Uploader for the package.  Also, the changelog entry of a QA upload has a
+special first line:
 </para>
+
+<screen>
+ * QA upload.
+</screen>
+
 <para>
-A binary-only NMU is a recompilation and upload of a binary package for a given
-architecture.  As such, it is usually part of a porting effort.  A binary-only
-NMU is a non-maintainer uploaded binary version of a package, with no source
-changes required.  There are many cases where porters must fix problems in the
-source in order to get them to compile for their target architecture; that
-would be considered a source NMU rather than a binary-only NMU.  As you can
-see, we don't distinguish in terminology between porter NMUs and non-porter
-NMUs.
+If you want to do an NMU, and it seems that the maintainer is not active, it is
+wise to check if the package is orphaned
+(this information is displayed on the package's Package Tracking System page).
+When doing the first QA upload to an
+orphaned package, the maintainer should be set to <literal>Debian QA Group
+&lt;packages@qa.debian.org&gt;</literal>.  Orphaned packages which did
+not yet have a QA upload still have their old maintainer set.  There is a list
+of them at <ulink url="&url-orphaned-not-qa;"/>.
 </para>
+
 <para>
-Both classes of NMUs, source and binary-only, can be lumped under the term
-``NMU''.  However, this often leads to confusion, since most people think
-``source NMU'' when they think ``NMU''.  So it's best to be careful: always use
-``binary NMU'' or ``binNMU'' for binary-only NMUs.
+Instead of doing a QA upload, you can also consider adopting the package by
+making yourself the maintainer.  You don't need permission from anybody to
+adopt an orphaned package, you can just set yourself as maintainer and upload
+the new version (see <xref linkend="adopting"/>).
 </para>
+
 </section>
 
 </section>