1dgit-maint-bpo(7)                    dgit                    dgit-maint-bpo(7)
2
3
4

NAME

6       dgit - tips for maintaining official Debian backports
7

INTRODUCTION

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

TERMINOLOGY

14       Let the master branch contain the packaging history uploaded to Debian
15       unstable, and the buster-bpo branch be where you prepare your uploads
16       to the buster-backports suite.
17
18       A merging backports workflow means that each time an upload migrates to
19       Debian testing and you want to prepare an upload to buster-backports,
20       you do something like this:
21
22           % git checkout buster-bpo
23           % git merge master
24           % dch --bpo
25           % # any other changes needed for backporting
26           % git commit -a
27           % # try a build
28
29       A rebasing backports workflow means that you throw away the history of
30       the buster-bpo branch each time a new version migrates to Debian
31       testing, something equivalent to this:
32
33           % git checkout -B buster-bpo master
34           % dch --bpo
35           % # any other changes needed for backporting
36           % git commit -a
37           % # try a build
38
39       If you use a merging backports workflow, your changelog contains
40       entries for each previous upload to buster-backports; in a rebasing
41       workflow, it contains only the latest.
42

CHOOSING BETWEEN THE TWO WORKFLOWS

44       If backporting involves making no (additional) changes to the upstream
45       source, whether you use a merging or rebasing backports workflow is a
46       matter of personal preference.  There are good arguments in favour of
47       both workflows fitting the semantics of the *-backports suites.
48
49       If you have to make changes to the upstream source to make the package
50       work on machines running Debian stable, it is advisable to choose a
51       rebasing workflow.  This ensures that dgit can automatically update the
52       debian/patches directory without any manual intervention.
53

TIPS FOR A MERGING WORKFLOW

55   Use dgit's branches
56       If you do not yourself upload the package to Debian unstable, it is
57       usually easiest to use dgit's branches, and ignore the configured Vcs-
58       Git repository.
59
60       You would use
61
62           % dgit clone foo bullseye
63
64       for a new backport of package 'foo' to buster-backports, and then
65
66           % dgit fetch bullseye
67           % git merge dgit/dgit/bullseye
68
69       when new versions migrate to Debian testing.
70

TIPS FOR A REBASING WORKFLOW

72   Use dgit's branches
73       If you do not yourself upload the package to Debian unstable, it is
74       usually easiest to use dgit's branches, and ignore the configured Vcs-
75       Git repository.  For each new version from Debian testing, you would
76
77           % dgit fetch bullseye
78           % git checkout -B buster-bpo dgit/dgit/bullseye
79           % # use git-cherry-pick(1) to (re)apply any needed backporting fixes
80
81   Overwriting
82       dgit push tries hard to prevent you from accidentally overwriting
83       uploads that it thinks aren't represented in the git history you are
84       trying to upload.  This is mainly to prevent accidentally overwriting
85       NMUs.
86
87       With a rebasing backports workflow, dgit will think that every upload
88       of a new version from Debian testing might be accidentally overwriting
89       uploads.  You will need to explicitly indicate the upload to buster-
90       backports you wish to overwrite.
91
92       Suppose that the last upload to buster-backports was versioned
93       1.2.2-1~bpo10+1 and you have now prepared 1.2.3-1~bpo10+1 for upload.
94       When you dgit push, you will need to pass --overwrite=1.2.2-1~bpo10+1.
95
96       Alternatively, you can perform the pseudomerge that --overwrite would
97       have done yourself:
98
99           % dgit fetch buster-backports
100           % git merge -s ours dgit/dgit/buster-backports
101           % dgit push-source
102

SEE ALSO

104       dgit(1), dgit(7), https://backports.debian.org/
105

AUTHOR

107       This manpage was written and is maintained by Sean Whitton
108       <spwhitton@spwhitton.name>.
109
110
111
112perl v5.30.0                    Debian Project               dgit-maint-bpo(7)
Impressum