Git workflow
============

Rationale
---------

The (E)LTS team manages several releases and many packages. To preserve
the history of all uploads, this Git workflow is mandatory.

All packages have a dedicated repository, referenced in the LTS/ELTS
(private) package database ``deblts-team/debian-lts:packages.yml``,
using the ``vcs`` field (and optionally ``vcs_elts``).

When following these steps, if you are not part of the LTS Team and
lack sufficient permissions, please mail the `LTS mailing list
<https://lists.debian.org/debian-lts/>`_ and request assistance.

.. contents:: :depth: 3


New repository
--------------

If no repositories are found in ``packages.yml``, by order of
preference:

Use the maintainers' repository
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Work directly in the maintainers' repository, or send merge and tag
requests, if they are willing to host LTS/ELTS work, and have a
`DEP-14 <https://dep-team.pages.debian.net/deps/dep14/>`_ layout
(where the branches are named according to the releases, such as
``debian/bullseye``).

Fork an existing repository
^^^^^^^^^^^^^^^^^^^^^^^^^^^

When the maintainers' repo is already at Salsa. Fork the repository
under the `lts-team/packages
<https://salsa.debian.org/lts-team/packages/>`_ namespace.

Note: forking existing repositories (rather than recreating them)
reduces resource consumption on Salsa and facilitates analyzing the history of the code.

Create a new repository
^^^^^^^^^^^^^^^^^^^^^^^

Last resort option, manually import the repository at Salsa.

You may also use these instructions to import missing versions in
existing repositories.

#. Go to the `main project <https://salsa.debian.org/lts-team/packages>`_ and press *New project* > `Create blank project <https://salsa.debian.org/projects/new?namespace_id=6008#blank_project>`_.
#. For the *Project name* field, enter the source package name.
#. Uncheck *Initialize repository with a README*.
#. *Create project*.

Clone the project on your computer:

.. code-block:: bash

  git clone git@salsa.debian.org:lts-team/packages/package.git

Use ``gbp import-dsc`` to import the initial version(s) of your
package. ``gbp import-dscs --debsnap`` can help import multiple
versions (but doesn't know about ELTS).

.. code-block:: bash

  dget .../<package>_1.2-3.dsc
  cd <package>/
  gbp import-dsc --debian-branch=debian/bullseye --pristine-tar ../bullseye-new/<package>_1.2-3.dsc
  gbp import-dsc --debian-branch=debian/bullseye --pristine-tar ../bullseye-new/<package>_1.2-3+deb11u1.dsc
  ...

  # or
  gbp import-dscs --debsnap --pristine-tar <package>
  git checkout -b debian/bullseye debian/<last_bullseye_tag>

Initial push:

.. code-block:: bash

  gbp push --debian-branch=debian/bullseye --pristine-tar
  # also push previous tags
  git push --tags

Clean-up branches
-----------------

#. *Settings > Repository > Branch defaults*: choose
   ``debian/bullseye``, *Save changes*.
#. *Code > Branches*: remove ``main`` branch if any.

gbp.conf
--------

Clean-up ``gbp.conf``, git-buildpackage's configuration file, to avoid
conflicts with the original configuration:

.. code-block:: bash

  cat <<'EOF' > debian/gbp.conf
  [DEFAULT]
  pristine-tar = True
  debian-branch = debian/bullseye
  EOF
  git commit -am 'Replace debian/gbp.conf'

Overlay repositories
--------------------

Repositories tracking only the ``debian/`` directory
(e.g. `firmware-free
<https://salsa.debian.org/kernel-team/firmware-free/>`_, `poppler
<https://salsa.debian.org/freedesktop-team/poppler>`_) are supported
by our workflow.

``gbp.conf`` is a bit different:
::

  [DEFAULT]
  debian-branch = debian/bullseye
  pristine-tar = False
  overlay = True
  export-dir = ..

The ``extract-source`` job will need a little help to find the source
tarball (as of 2025-07 it `only supports sid
<https://salsa.debian.org/salsa-ci-team/pipeline/-/issues/452>`_):

 - ensure ``origtargz`` works, e.g. ``uscan --download-current-version``
 - add a ``pristine-tar`` branch anyway (at the cost of a heavier Git repo)

Troubleshooting: ``not a valid treeish``: GBP didn't find the tarball
in the parent directory and attempted to get it from Git. Re-check
your tarball presence and name.

Setting up CI
-------------

Each package must have a working CI (continuous integration)
pipeline. An exception can be granted to some large or difficult
packages where the CI is difficult to setup or is impossible for some
technical reason. Each exception should be discussed on the `LTS
mailing list`_.

Project configuration
^^^^^^^^^^^^^^^^^^^^^

#. Go to *Settings > CI/CD*. Expand *General pipelines*:

   #. *CI/CD configuration file*: **debian/salsa-ci.yml**
   #. *Timeout*: **6h** (note: this is capped by the Runner's
      timeout, current 3h, and `SALSA_CI_BUILD_TIMEOUT_ARGS
      <https://salsa.debian.org/lts-team/pipeline/-/blob/master/salsa-ci.yml>`_,
      currently 2.75h)
   #. *Save changes*.

#. Expand *Runners*. Ensure there's an **ARM runner** enabled: LTS
   Team ARM runner and/or salsaci-arm64-runner*. (Currently down as of
   2025-09 following sponsorship drop, but should be replaced.)

salsa-ci.yml
^^^^^^^^^^^^

#. Create or modify **debian/salsa-ci.yml** with the following
   (replacing ``DIST`` with ``bullseye``/``buster``/etc.):
   ::

       ---
       # LTS/ELTS CI

       include:
       - https://salsa.debian.org/lts-team/pipeline/raw/master/recipes/DIST.yml

       # These didn't work before LTS, not attempting to fix after freeze
       #blhc:
       #  allow_failure: true

       # Or skip some tests entirely:
       #variables:
       #  SALSA_CI_DISABLE_BLHC: 1

   The full documentation for the Debian pipeline may be found in the
   `lts-team/pipeline repository
   <https://salsa.debian.org/lts-team/pipeline>`_.

#. Commit and push the file:

   .. code-block:: bash

       git add debian/salsa-ci.yml
       git commit -am 'Add debian/salsa-ci.yml'
       git push

If all went well, your package is being built at *Build > Pipelines*.

To avoid triggering the CI for trivial changes:

   .. code-block:: bash

       git push -o ci.skip

.. image:: /_static/git-workflow-lts/CI-successfull.png
   :target: /_static/git-workflow-lts/CI-successfull.png
   :alt: A test image


Prepare an upload of the already existing package
-------------------------------------------------

Note: specify options even if we added them to ``gbp.conf`` above, in
case we're working on a package with a pre-LTS or missing
``gbp.conf``.

#. Clone an existing repository:

   .. code-block:: bash

       gbp clone git@salsa.debian.org:lts-team/packages/package.git
       # note: grabs and checks-out upstream, pristine-tar, etc. branches

#. Hack on the package

#. Try to build locally:

   .. code-block:: bash

       gbp buildpackage --git-debian-branch=debian/bullseye ...

#. After ``git push`` you can check the CI in *Build > Pipelines*.

#. If the build was successful, tag the package:

   .. code-block:: bash

       gbp tag --debian-branch=debian/bullseye
       gbp push --debian-branch=debian/bullseye --pristine-tar