Bug#749826: Documenting `Multi-Arch: foreign`

diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -1307,6 +1307,166 @@ This list is intentionally incomplete. You should consult the
 documentation of the tool or package in question for which keywords it
 defines and when they are needed.
 
+.. _s-f-Multi-Arch:
+
+``Multi-Arch``
+~~~~~~~~~~~~~~
+
+A Debian installation can combine packages from multiple architectures.
+The ``Multi-Arch`` header enables individual packages to declare their
+support for this feature, and influences the way dependencies are
+handled.  It can be declared in binary package sections of a source
+package template control file and in binary package control files.  The
+permitted header values are ``no`` (default), ``foreign``, ``same`` and
+``allowed``. Their semantics are described in the following sections.
+
+.. _s-f-Multi-Arch-no:
+
+``Multi-Arch: no``
+^^^^^^^^^^^^^^^^^^
+
+This means that a ``Depends``, ``Pre-Depends``, ``Provides``,
+``Recommends`` or ``Suggests`` relation between packages is satisfied
+only by packages of the same architecture.  There is no effect on
+``Breaks``, ``Conflicts`` and ``Replaces``.  Furthermore, multiple
+instances of a package with the same name but different architectures
+cannot be installed at the same time.  Architecture-independent packages
+are treated as though they had the architecture value of the installed
+``dpkg`` package.
+
+Note that, due to limitations in the archive management software, this
+value cannot currently be specified explicitly in binary package control
+files.  Instead, the field needs to be absent in order to imply its
+default value and ``debhelper`` discards it when transforming a source
+package control template.
+
+``Multi-Arch: foreign``
+^^^^^^^^^^^^^^^^^^^^^^^
+
+This means that the interfaces the package provides are independent of
+its architecture, and that it therefore satisfies dependencies on a
+package of this name regardless of the architecture of the package
+declaring the dependency. Any virtual packages provided (see
+:ref:`s-virtual`) inherit this property.
+
+There are five main areas that can contribute to the interface of a
+package. If any of them provides an architecture-dependent interface, a
+package must not be marked with ``Multi-Arch: foreign``. Note that
+architecture-independent packages can reasonably provide
+architecture-dependent interfaces and therefore
+architecture-independent packages are not implicitly treated as
+``Multi-Arch: foreign``.
+
+- The installed files of a package: Architecture-dependent packages may
+  install different sets of files or files with different content for
+  different architectures. These differences may contribute to the
+  interface (e.g. an endianness-dependent database file).  For
+  architecture-independent binary packages, this aspect does not apply.
+
+- The behavior of package's installed files: packages usually have
+  an expected way of having their files used. They may be executed or
+  interpreted. If the architecture of the package that installed them is
+  exposed in the process of their intended use, their interface is
+  considered architecture-dependent.
+
+  For instance, shared and static libraries are inherently
+  architecture-dependent. They therefore prohibit the use of
+  ``Multi-Arch: foreign`` unless they are not intended to be used by
+  other packages.  Whilst binary executables generally differ across
+  architectures, the exposed interface can be independent of the
+  architecture used to execute. Architecture exposure can happen via the
+  command line arguments, the data exchanged or the way they process
+  files. Last but not least, data files can have architecture-dependent
+  structure.
+
+- Maintainer scripts and triggers: A package can behave in an
+  architecture dependent way, when the behavior of maintainer scripts or
+  invoked triggers depends on the architecture. For instance,
+  byte-compiling source files into architecture-dependent bytecode
+  during ``postinst`` may turn the interface of a package
+  architecture-dependent.
+
+- The dependencies of a package: A package may expose functionality of
+  other packages by depending on them and thereby provide an
+  architecture-dependent interface itself. The ABI of a shared library
+  linked into an executable does not usually contribute to the
+  interface, but the behavior of library functions used may do so.
+  Development packages for shared libraries necessarily expose their own
+  dependencies as their interface since they enable others to link such
+  libraries. An extreme example is transitional packages, whose main
+  purpose is to expose the functionality of their dependency. Therefore,
+  transitional packages should copy the ``Architecture`` and
+  ``Multi-Arch`` field from their target.
+
+- Implicit and foreign dependencies of a package: Essential packages are
+  implicitly depended upon and need not be included in ``Depends``. Yet
+  their behaviour can be architecture-dependent. For instance, using
+  ``dpkg --print-architecture`` can be used to emit the native
+  architecture even though ``dpkg`` is marked ``Multi-Arch: foreign``.
+  Similarly, calling ``pkgconf`` (without a prefix) will behave
+  differently on different architectures as its search path is
+  architecture-dependent even though ``pkgconf-bin`` is considered
+  ``Multi-Arch: foreign``.
+
+The interfaces of a package are determined by its maintainer.  However,
+some packages might expose architecture-specific dependencies when other
+packages use them in a manner not intended by the maintainer.  This can
+happen when it is not clear which parts of the package are its
+interfaces.
+
+In such cases, where the package satisfies the criterion for
+``Multi-Arch: foreign`` but might expose architecture dependency,
+because it is not clear which parts of the package are its interfaces,
+the interfaces of the package should be described in the file
+``debian/README.multiarch``.
+
+Conversely, packages must not use other packages in ways declined by
+their ``debian/README.multiarch``.
+
+``Multi-Arch: same``
+^^^^^^^^^^^^^^^^^^^^
+
+This means that other packages with the exact same name and version, but
+different architectures, can be installed concurrently.  All those
+packages  must be declared ``Multi-Arch: same``.
+
+For a given file name, if the package for one architecture installs a
+file there, then the packages for every other architecture must either
+install no file there, or a bit-identical file.  Given this restriction,
+such packages usually install most of their files below
+``/usr/lib/${DEB_HOST_MULTIARCH}``.
+
+The maintainer scripts must be prepared to be configured or deconfigured
+multiple times. In particular, ``postrm`` must not assume that all
+instances of the package (e.g., instances for other architectures) are
+gone. It may check the ``DPKG_MAINTSCRIPT_PACKAGE_REFCOUNT`` environment
+variable set by ``dpkg``.
+
+``Multi-Arch: allowed``
+^^^^^^^^^^^^^^^^^^^^^^^
+
+This means the same as ``Multi-Arch: no`` except that a package
+depending on this package may choose to treat it as though it were
+marked ``Multi-Arch: foreign``.  This is done by appending ``:any`` to
+the name of the package in the dependency relation field.  For example,
+where foo is ``Multi-Arch: allowed``, bar might have ``Depends: foo:any
+(>= 1.0)``.  Then bar's dependency on foo is satisfied even when bar and
+foo have different architectures.
+
+Only a ``Multi-Arch: allowed`` package satisfies a dependency with the
+``:any`` suffix.
+
+This value should be used rarely. It exists for cases where the package
+can be used in an architecture-dependent way or in an
+architecture-independent way and the decision of which applies is
+deferred to the depender. The most common use is with programming
+language interpreters that enable loading architecture-dependent
+plugins.
+
+Since removing this value tends to break reverse dependencies that
+employ ``:any``, uses of it should be discussed with
+*[email protected]* first.
+
 .. _s5.7:
 
 User-defined fields
@@ -1443,3 +1601,9 @@ details.
 
 .. [#]
    That is, the parts which are not the ``.dsc``.
+
+.. [#]
+   As an exception, the ``libc6`` package is marked ``Multi-Arch: same``
+   despite not fully complying with this requirement, because the
+   location of the dynamic loader is not unique across architectures and
+   cannot be changed without breakig ABI.