dgit-maint-bpo.7.pod

   1 =head1 NAME
   2
   3 dgit - tips for maintaining official Debian backports
   4
   5 =head1 INTRODUCTION
   6
   7 This document describes elements of a workflow for using B<dgit> to
   8 maintain an official Debian backport.  We do not assume that whoever
   9 uploads the package to Debian unstable is using B<dgit>.
  10
  11 =head1 TERMINOLOGY
  12
  13 Let the I<master> branch contain the packaging history uploaded to
  14 Debian unstable, and the I<buster-bpo> branch be where you prepare
  15 your uploads to the B<buster-backports> suite.
  16
  17 A B<merging> backports workflow means that each time an upload
  18 migrates to Debian testing and you want to prepare an upload to
  19 B<buster-backports>, you do something like this:
  20
  21 =over 4
  22
  23     % git checkout buster-bpo
  24     % git merge master
  25     % dch --bpo
  26     % # any other changes needed for backporting
  27     % git commit -a
  28     % # try a build
  29
  30 =back
  31
  32 A B<rebasing> backports workflow means that you throw away the history
  33 of the I<buster-bpo> branch each time a new version migrates to Debian
  34 testing, something equivalent to this:
  35
  36 =over 4
  37
  38     % git checkout -B buster-bpo master
  39     % dch --bpo
  40     % # any other changes needed for backporting
  41     % git commit -a
  42     % # try a build
  43
  44 =back
  45
  46 If you use a merging backports workflow, your changelog contains
  47 entries for each previous upload to B<buster-backports>; in a rebasing
  48 workflow, it contains only the latest.
  49
  50 =head1 CHOOSING BETWEEN THE TWO WORKFLOWS
  51
  52 If backporting involves making no (additional) changes to the upstream
  53 source, whether you use a merging or rebasing backports workflow is a
  54 matter of personal preference.  There are good arguments in favour of
  55 both workflows fitting the semantics of the B<*-backports> suites.
  56
  57 If you have to make changes to the upstream source to make the package
  58 work on machines running Debian stable, it is advisable to choose a
  59 rebasing workflow.  This ensures that dgit can automatically update
  60 the debian/patches directory without any manual intervention.
  61
  62 =head1 TIPS FOR A MERGING WORKFLOW
  63
  64 =head2 Use dgit's branches
  65
  66 If you do not yourself upload the package to Debian unstable, it is
  67 usually easiest to use dgit's branches, and ignore the configured
  68 Vcs-Git repository.
  69
  70 You would use
  71
  72 =over 4
  73
  74     % dgit clone foo bullseye
  75
  76 =back
  77
  78 for a new backport of package 'foo' to B<buster-backports>, and then
  79
  80 =over 4
  81
  82     % dgit fetch bullseye
  83     % git merge dgit/dgit/bullseye
  84
  85 =back
  86
  87 when new versions migrate to Debian testing.
  88
  89 =head1 TIPS FOR A REBASING WORKFLOW
  90
  91 =head2 Use dgit's branches
  92
  93 If you do not yourself upload the package to Debian unstable, it is
  94 usually easiest to use dgit's branches, and ignore the configured
  95 Vcs-Git repository.  For each new version from Debian testing, you
  96 would
  97
  98 =over 4
  99
 100     % dgit fetch bullseye
 101     % git checkout -B buster-bpo dgit/dgit/bullseye
 102     % # use git-cherry-pick(1) to (re)apply any needed backporting fixes
 103
 104 =back
 105
 106 =head2 Overwriting
 107
 108 B<dgit push> tries hard to prevent you from accidentally overwriting
 109 uploads that it thinks aren't represented in the git history you are
 110 trying to upload.  This is mainly to prevent accidentally overwriting
 111 NMUs.
 112
 113 With a rebasing backports workflow, dgit will think that every upload
 114 of a new version from Debian testing might be accidentally overwriting
 115 uploads.  You will need to explicitly indicate the upload to
 116 B<buster-backports> you wish to overwrite.
 117
 118 Suppose that the last upload to B<buster-backports> was versioned
 119 I<1.2.2-1~bpo10+1> and you have now prepared I<1.2.3-1~bpo10+1> for
 120 upload.  When you B<dgit push>, you will need to pass
 121 I<--overwrite=1.2.2-1~bpo10+1>.
 122
 123 Alternatively, you can perform the pseudomerge that I<--overwrite>
 124 would have done yourself:
 125
 126 =over 4
 127
 128     % dgit fetch buster-backports
 129     % git merge -s ours dgit/dgit/buster-backports
 130     % dgit push-source
 131
 132 =back
 133
 134 =head1 SEE ALSO
 135
 136 dgit(1), dgit(7), https://backports.debian.org/
 137
 138 =head1 AUTHOR
 139
 140 This manpage was written and is maintained by Sean Whitton
 141 <spwhitton@spwhitton.name>.