summaryrefslogtreecommitdiff
path: root/dgit-maint-bpo.7.pod
blob: 86372dd575cf5ee6af4584e2fa9afd4f28bd55b1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
=head1 NAME

dgit - tips for maintaining official Debian backports

=head1 INTRODUCTION

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

=head1 GENERAL TIPS

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

=head1 TERMINOLOGY

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

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

=over 4

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

=back

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

=over 4

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

=back

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

=head1 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 B<*-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.

=head1 TIPS FOR A MERGING WORKFLOW

=head2 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

=over 4

    % dgit clone foo bullseye

=back

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

=over 4

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

=back

when new versions migrate to Debian testing.

=head1 TIPS FOR A REBASING WORKFLOW

=head2 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

=over 4

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

=back

=head2 Overwriting

B<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
B<buster-backports> you wish to overwrite.

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

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

=over 4

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

=back

=head1 SEE ALSO

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

=head1 AUTHOR

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