.. collection:: debian:suite

Category ``debian:suite``
-------------------------

This collection represents a single `suite
<https://wiki.debian.org/DebianRepository/Format#Suite>`_ in a Debian
archive. Its ``name`` is the name of the suite.

* Variables when adding items:

  * ``component``: the component (e.g. ``main`` or ``non-free``) in which
    this package is published
  * ``section``: the section (e.g. ``python``) for this package
  * ``priority``: for binary packages, the priority (e.g. ``optional``) for
    this package
  * ``build_id``: for :artifact:`debian:debug-symbols` artifacts, the
    40-character hexadecimal GNU build-ID for the collection item being
    added (one item is created per build-ID)

* Data:

  * ``components``: the components that exist in this suite (must be set in
    order to be able to generate indexes)
  * ``architectures``: the architectures that exist in this suite (must be
    set in order to be able to generate indexes)
  * ``release_fields``: dictionary of static fields to set in this suite's
    ``Release`` file
  * ``may_reuse_versions``: if true, versions of packages in this suite may
    be reused provided that the previous packages with that version have
    been removed; this should be false for typical user-facing suites to
    avoid confusing behaviour from apt, but it may be useful to set it to
    true for experimental suites or for suites mirrored from elsewhere
  * ``may_rewind_versions``: if true, package versions added to this suite
    may be earlier than versions already active in the suite; this should be
    false for typical user-facing suites to avoid confusing behaviour from
    apt, but it may be useful to set it to true for experimental suites or
    for suites mirrored from elsewhere
  * ``duplicate_architecture_all``: if true, include ``Architecture: all``
    packages in architecture-specific ``Packages`` indexes, and set
    `No-Support-for-Architecture-all: Packages
    <https://wiki.debian.org/DebianRepository/Format#No-Support-for-Architecture-all>`__
    in the ``Release`` file; this may improve compatibility with older
    client code
  * ``signing_keys`` (list of strings, optional): the fingerprints of the
    :asset:`debusine:signing-key` assets to sign repository indexes in this
    suite with, which must each have purpose ``openpgp``; if not set, then
    the containing :collection:`archive <debian:archive>` controls which
    signing keys are used
  * ``exported`` (boolean, defaults to True): if False, do not generate
    indexes for this suite and do not publish it via archive access views

* Valid items:

  * :artifact:`debian:source-package` artifacts
  * :artifact:`debian:binary-package` artifacts
  * :artifact:`debian:debug-symbols` artifacts
  * :artifact:`debian:repository-index` artifacts

* Per-item data:

  * ``srcpkg_name``: for binary packages and debug symbols, the name of the
    corresponding source package (copied from the underlying binary package
    artifact for ease of lookup and to preserve history)
  * ``srcpkg_version``: for binary packages and debug symbols, the version
    of the corresponding source package (copied from the underlying binary
    package artifact for ease of lookup and to preserve history)
  * ``package``: the name from the package's ``Package:`` field (copied from
    underlying artifact for ease of lookup and to preserve history); for
    debug symbols, copied from the related binary package
  * ``version``: the version of the package (copied from underlying artifact
    for ease of lookup and to preserve history); for debug symbols,
    copied from the related binary package
  * ``architecture``: for binary packages and debug symbols, the
    architecture of the package (copied from underlying artifact for ease of
    lookup and to preserve history)
  * ``component``: the component (e.g. ``main`` or ``non-free``) in which
    this package is published
  * ``section``: the section (e.g. ``python``) for this package
  * ``priority``: for binary packages, the priority (e.g. ``optional``) for
    this package
  * ``build_id``: for debug symbols, the 40-character hexadecimal GNU
    build-ID this collection item represents
  * ``path``: for index files, the path of the file relative to the root of
    the suite's directory in ``dists`` (e.g. ``InRelease`` or
    ``main/source/Sources.xz``)

Collection items for :artifact:`debian:debug-symbols` are named
``debugsym:{package}_{version}_{architecture}_{build_id}``.  Adding such an
item requires exactly one related :artifact:`debian:binary-package` via a
``relates-to`` relation from the debug-symbols artifact.

* Lookup names:

  * ``source:NAME``: the current version of the source package named
    ``NAME``.
  * ``source-version:NAME_VERSION``: the source package named ``NAME`` at
    ``VERSION``.
  * ``binary:NAME_ARCHITECTURE`` the current version of the binary package
    named ``NAME`` on ``ARCHITECTURE`` (also including ``Architecture: all``
    binary packages if ``ARCHITECTURE`` is not ``all``).
  * ``binary-version:NAME_VERSION_ARCHITECTURE`` the binary package named
    ``NAME`` at ``VERSION`` on ``ARCHITECTURE`` (also including
    ``Architecture: all`` binary packages if ``ARCHITECTURE`` is not
    ``all``).
  * ``index:PATH``: the current index file at ``PATH`` relative to the root
    of the suite's directory in ``dists``

* Multiple lookup filters:

  * ``binaries``: given a :ref:`lookup-single` or :ref:`lookup-multiple`
    referring to zero or more source packages, return the binary packages
    built by those source packages that are active in this suite

* Constraints:

  * there may be at most one package with a given name and version (and
    architecture, in the case of binary packages) active in the collection
    at a given time
  * each poolified file name resulting from an active artifact may only
    refer to at most one concrete file in the collection at a given time
    (this differs from the above constraint in the case of source packages,
    which contain multiple files that may overlap with other source
    packages)
  * if ``may_reuse_versions`` is false, then each poolified file name in the
    collection may only refer to at most one concrete file, regardless of
    whether conflicting files are active or removed

Several :artifact:`debian:debug-symbols` items may share a build-ID, and
their files need not have identical contents: a source package may install
the same object into more than one binary package, and ``dh_dwz`` runs once
per binary package, so only some of the resulting ``.debug`` files refer to
a DWZ supplement.  Following ``debuginfod(8)``, a request for such a
build-ID is answered with the file from the most recently created
artifact.

To support race-free mirroring, repository index files are served via
`by-hash
<https://wiki.debian.org/DebianRepository/Format#indices_acquisition_via_hashsums_.28by-hash.29>`__
paths in addition to their base path.  These paths are handled implicitly by
the code that serves repositories, and are not recorded using separate
collection items.
