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

GENERAL TIPS

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

TERMINOLOGY

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

CHOOSING BETWEEN THE TWO WORKFLOWS

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

TIPS FOR A MERGING WORKFLOW

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

TIPS FOR A REBASING WORKFLOW

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

SEE ALSO

108       dgit(1), dgit(7), https://backports.debian.org/
109

AUTHOR

111       This manpage was written and is maintained by Sean Whitton
112       <spwhitton@spwhitton.name>.
113
114
115
116perl v5.32.1                    Debian Project               dgit-maint-bpo(7)
Impressum