dgit-maint-bpo

dgit-maint-bpo(7)                    dgit                    dgit-maint-bpo(7)



NAME
       dgit - tips for maintaining official Debian backports

INTRODUCTION
       This document describes elements of a workflow for using dgit to
       maintain an official Debian backport.  We do not assume that whoever
       uploads the package to Debian unstable is using dgit.

GENERAL TIPS
       The first time a package is backported for any particular Debian
       release, you will have to pass the --new option to dgit.

TERMINOLOGY
       Let the master branch contain the packaging history uploaded to Debian
       unstable, and the buster-bpo branch be where you prepare your uploads
       to the buster-backports suite.

       A merging backports workflow means that each time an upload migrates to
       Debian testing and you want to prepare an upload to buster-backports,
       you do something like this:

           % git checkout buster-bpo
           % git merge master
           % dch --bpo
           % # any other changes needed for backporting
           % git commit -a
           % # try a build

       A rebasing backports workflow means that you throw away the history of
       the buster-bpo branch each time a new version migrates to Debian
       testing, something equivalent to this:

           % git checkout -B buster-bpo master
           % dch --bpo
           % # any other changes needed for backporting
           % git commit -a
           % # try a build

       If you use a merging backports workflow, your changelog contains
       entries for each previous upload to buster-backports; in a rebasing
       workflow, it contains only the latest.

CHOOSING BETWEEN THE TWO WORKFLOWS
       If backporting involves making no (additional) changes to the upstream
       source, whether you use a merging or rebasing backports workflow is a
       matter of personal preference.  There are good arguments in favour of
       both workflows fitting the semantics of the *-backports suites.

       If you have to make changes to the upstream source to make the package
       work on machines running Debian stable, it is advisable to choose a
       rebasing workflow.  This ensures that dgit can automatically update the
       debian/patches directory without any manual intervention.

TIPS FOR A MERGING WORKFLOW
   Use dgit's branches
       If you do not yourself upload the package to Debian unstable, it is
       usually easiest to use dgit's branches, and ignore the configured Vcs-
       Git repository.

       You would use

           % dgit clone foo bullseye

       for a new backport of package 'foo' to buster-backports, and then

           % dgit fetch bullseye
           % git merge dgit/dgit/bullseye

       when new versions migrate to Debian testing.

TIPS FOR A REBASING WORKFLOW
   Use dgit's branches
       If you do not yourself upload the package to Debian unstable, it is
       usually easiest to use dgit's branches, and ignore the configured Vcs-
       Git repository.  For each new version from Debian testing, you would

           % dgit fetch bullseye
           % git checkout -B buster-bpo dgit/dgit/bullseye
           % # use git-cherry-pick(1) to (re)apply any needed backporting fixes

   Overwriting
       dgit push tries hard to prevent you from accidentally overwriting
       uploads that it thinks aren't represented in the git history you are
       trying to upload.  This is mainly to prevent accidentally overwriting
       NMUs.

       With a rebasing backports workflow, dgit will think that every upload
       of a new version from Debian testing might be accidentally overwriting
       uploads.  You will need to explicitly indicate the upload to buster-
       backports you wish to overwrite.

       Suppose that the last upload to buster-backports was versioned
       1.2.2-1~bpo10+1 and you have now prepared 1.2.3-1~bpo10+1 for upload.
       When you dgit push, you will need to pass --overwrite=1.2.2-1~bpo10+1.

       Alternatively, you can perform the pseudomerge that --overwrite would
       have done yourself:

           % dgit fetch buster-backports
           % git merge -s ours dgit/dgit/buster-backports
           % dgit push-source

SEE ALSO
       dgit(1), dgit(7), https://backports.debian.org/

AUTHOR
       This manpage was written and is maintained by Sean Whitton
       <spwhitton@spwhitton.name>.



perl v5.28.2                    Debian Project               dgit-maint-bpo(7)