.. _mail-forwarding:

Forwarding Mails through the Package Tracker
===========================================

General Principle
-----------------

The email messages to forward are received through the
:samp:`dispatch@{distro-tracker-domain}` email address.

Distro Tracker is usually able to analyze the email messages from common
tools (debbugs, DAK, GitLab, etc.) and to figure out the name of the
package and the associated :ref:`keyword <keywords>`. If that is not the case,
there are two ways to pass the required package/keyword data:

* either by adding the ``X-Distro-Tracker-Package`` and
  ``X-Distro-Tracker-Keyword`` `headers <mail-headers>`_ in the mail sent to
  the :samp:`dispatch@{distro-tracker-domain}` email address;
* or by sending the mails to :samp:`dispatch+{package}@{distro-tracker-domain}`
  or :samp:`dispatch+{package}_{keyword}@{distro-tracker-domain}`.

Once the package and keyword are known, the message can be forwarded to
the package subscribers who have the corresponding keyword enabled.

.. warning::

    When Distro-Tracker has been unable to find a keyword for the message,
    it will assign the ``default`` keyword. To prevent random spam from
    being forwarded through the package tracker, a message with the
    ``default`` keyword will only be forwarded if it contains the
    ``X-Distro-Tracker-Approved`` header with a non-empty value. 

.. note::

    Each :ref:`vendor <vendor-customization>` can provide their own set of
    available keywords and a set of rules to tag incoming messages with
    one of the keywords. If there is no such tagging mechanism and no
    keyword in the local part of the email address, the message is tagged
    with the ``default`` keyword.

.. _forwarding-vcs-commits:

Forwarding VCS Commits to the Package Tracker
---------------------------------------------

If you use a publicly accessible VCS repository for maintaining your
Debian package, you may want to forward the commit notifications to the
package tracker so that the subscribers (and possible co-maintainers) can
closely follow the package's evolution.

Debian's Distro Tracker knows how to parse email notifications generated by
GitLab's *Email on Pushes* integration or by Git's *git-multimail.py*
hook script. It assumes that the name of the git repository (with the
eventual ``.git`` suffix stripped) is the name of the source package and
it will automatically affect the `vcs` keyword to those messages.
Thanks to this, you just have to configure your git repository to send
the notifications to dispatch@tracker.debian.org.

.. note::

    The git commit emails are recognized by their ``X-GitLab-Project`` or
    ``X-Git-Repo`` headers. Those fields are parsed as a path whose last
    component is the name of the source package (with a possible ``.git``
    suffix.

If you use another tool that doesn't generate any of the recognized headers
(or if your Git repositories are not named after the source package name),
you will have to send your VCS commit notification mails to
:samp:`dispatch+{sourcepackage}_vcs@{distro-tracker-domain}`.