Patch Pilot Git Ubuntu Tips
===========================

Contributors can propose source package updates in a number of different ways
within the `Patch Pilot Program
<https://discourse.ubuntu.com/t/ubuntu-patch-pilots/37705>`_, such as
traditional debdiffs and git-ubuntu merge proposals.  This document serves to
answer specific technical questions regarding the latter.


How do I handle Patch Pilot contributions that use git-ubuntu?
--------------------------------------------------------------

The following is a typical workflow for handling a git-ubuntu-based
contribution:

1. Install git-ubuntu
2. Clone the source package's official git-ubuntu repo
3. Add the contributor's remote tracking branch branch to the checkout
4. Review the branch
5. Build the proposed source package
6. Run autopkgtests

These steps are described in the sections below.


How do I checkout the source package's official git-ubuntu repo?
----------------------------------------------------------------

::

    $ git ubuntu clone <package> [dir-name]

For example, for a contribution to dovecot, you might run::

    $ git ubuntu clone dovecot dovecot-gu


How do I add remote tracking branches to a git-ubuntu checkout?
---------------------------------------------------------------

In order to review the sponsoree's changes, you'll want to add their
Launchpad username to your local checkout::

    $ git ubuntu remote add <sponsoree>
    $ git checkout "<sponsoree>/<branch_name>" -b "<branch_name>"



How can I view the current state of the package for a given release?
--------------------------------------------------------------------

By default the `git ubuntu clone` command will checkout a branch named
'ubuntu/devel' that corresponds to the current Ubuntu development
release.  If you wish to examine the version of the source package for a
different Ubuntu version, git-ubuntu provides branches tracking all
releases and pockets.  For example::

    $ git branch -av | grep pkg/ubuntu/jammy
      remotes/pkg/ubuntu/jammy                         17f59d728 1:2.3.16+dfsg1-3ubuntu2 (patches unapplied)
      remotes/pkg/ubuntu/jammy-devel                   f5217e4fc changelog
      remotes/pkg/ubuntu/jammy-proposed                f5217e4fc changelog
      remotes/pkg/ubuntu/jammy-security                20252305d 1:2.3.16+dfsg1-3ubuntu2.1 (patches unapplied)
      remotes/pkg/ubuntu/jammy-updates                 f5217e4fc changelog

Most commonly, it will be the -devel branch you're interested in for
patch piloting work, so in general for the current jammy version of the
package, you would typically want to run::

    $ git checkout pkg/ubuntu/jammy-devel -b jammy-devel

Be aware that the -devel branch will include any changes currently
staged in -proposed that haven't been released yet.  If the git hash
for -devel doesn't match with at least one of the release pockets, that
may indicate this discrepancy.  In that case, some additional action may
be needed before the new changes can be uploaded.


How can I convert a debdiff contribution into a git-ubuntu branch?
------------------------------------------------------------------

Traditional contributions to Patch Pilot are in debdiff form, and in
terms of policy may be fine to handle directly, without use of
git-ubuntu.  However, if you prefer to handle it through git-ubuntu, you
may find the following workflow useful.

::

    $ mkdir review-lp<num>
    $ cd review-lp<num>
    $ wget <url-debdiff>
    $ git ubuntu clone <package> <package>-gu
    $ cd <package>-gu
    $ git checkout pkg/ubuntu/<release>-devel -b review-lp<num>-<release>
    $ debdiff-apply < ../<debdiff>
    $ git commit debian/changelog -m changelog
    $ changes=$(dpkg-parsechangelog -S Changes | grep "^ ")
    $ update-maintainer -r
    Restoring original maintainer: ...
    $ git commit -a -m "${changes}"
    $ update-maintainer
    $ git commit debian/control* -m "update-maintainer"

That should result in a reasonable facsimile of a git ubuntu style
branch.  Depending on the contribution you might want to improve the
commit message or split the changes up into several commits instead of
one.

Once you're happy, you can proceed with reviewing and building using the
techniques described elsewhere.

For more info about traditional debdiff-based contributing, see the
`Reviewer Team's Knowledge Base <https://wiki.ubuntu.com/ReviewersTeam/KnowledgeBase>`_.


How do I deal with git-based contributions not in git-ubuntu?
-------------------------------------------------------------


What is the "empty directories" quirk and how do I handle it?
-------------------------------------------------------------

.. code-block:: none

    WARNING: empty directories exist but are not tracked by git:
    These will silently disappear on commit, causing extraneous
    unintended changes. See: LP: #1687057.
    Use "git commit --no-verify ..." to ignore this problem.

Source packages can ship with empty directories, but git's frontend
doesn't allow adding empty directories.  This can cause some confusion
for git ubuntu.  For patch piloting this is worth being aware of, since
the workaround needs to be done at point of upload.

For a full explanation and steps on how to handle it, see the
:doc:`Restore empty directories howto </howto/restore-empty-directories>`.


How do I build a git-ubuntu source package branch for uploading?
----------------------------------------------------------------

Assuming you have the branch checked out that you want to build, and are
running inside an Ubuntu release matching the MP's release (e.g. in an
LXC container), here is one way to build the source package from the
branch::

    $ install-build-deps
    $ git ubuntu export-orig [--for-merge]
    $ upload_args=$(git ubuntu prepare-upload args)
    $ debuild --no-lintian -S -uc -us ${upload_args}

Following this workflow, with use of prepare-upload, the rich history
in the git commit log will be preserved and shared with other packagers,
and the merge proposal will get marked merged automatically.

The `install-build-deps` script can be found in the ubuntu-helpers repository, or
you can download it directly from:

    https://git.launchpad.net/~ubuntu-server/+git/ubuntu-helpers/plain/bryce/install-build-deps

This calculates the build requirements using the debian/control file in
the current directory tree.  This is more reliable than using
`apt-get build-dep <package>` when the changes you're reviewing have
some package dependency changes, such as when merging a new upstream
package.


How do I run autopkgtests against a git-ubuntu branch?
------------------------------------------------------

Here's a workflow snippet to toss the changes into a PPA and run tests
on that::

    $ ppa="ppa:<username>/<package>-review-lp<num>"
    $ ppa create ${ppa}
    $ dput ${ppa} <source-changes-file>
    $ ppa wait ${ppa}
    $ ppa tests ${ppa}

The last command will print clickable links to trigger the corresponding
autopkgtests.  When triggering them, keep in mind not all architectures
may be available in the PPA build.

If someone has already provided a PPA with a successfully built package,
you can skip most of that and just run the last command.  If another
pilot has already run the tests, then that'll print the results.

Since autopkgtests can take a while to run, you may want to consider
triggering them and then handing off the remainder of the review to the
next patch pilot.


What to do when prepare-upload takes too long?
----------------------------------------------

How do I close someone's git-ubuntu MP?
---------------------------------------

Until the `staging branches feature
<https://discourse.ubuntu.com/t/spec-git-ubuntu-staged-uploads/35409>`_
lands, as a stop-gap please ask for the the MP to be closed for you, with an
explanation as to why and whether it should be set to Merged or Rejected.

Canonical employees: in Mattermost on the "Patch Pilot v2" channel, mention
``git-ubuntu-help`` to request this.

General public: use #ubuntu-devel on Libera.Chat, mentioning
``git-ubuntu-help``.

For example:

    git-ubuntu-help please mark
    https://code.launchpad.net/~abc/ubuntu/+source/hello/+git/foo/+merge/123
    as merged as it has been uploaded.


Where can I get more detailed information about the Patch Pilot program?
------------------------------------------------------------------------

https://wiki.ubuntu.com/ReviewersTeam/KnowledgeBase

https://discourse.ubuntu.com/t/ubuntu-patch-pilots/37705

Where can I get more detailed information about git-ubuntu?
-----------------------------------------------------------

The :doc:`official documentation for git-ubuntu </index>` is
hosted on Read the Docs, and `its codebase can be found on
Launchpad <https://git.launchpad.net/git-ubuntu>`_.
