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