.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "dgit-maint-bpo 7" .TH dgit-maint-bpo 7 "Debian Project" "perl v5.28.1" "dgit" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" dgit \- tips for maintaining official Debian backports .SH "INTRODUCTION" .IX Header "INTRODUCTION" This document describes elements of a workflow for using \fBdgit\fR to maintain an official Debian backport. We do not assume that whoever uploads the package to Debian unstable is using \fBdgit\fR. .SH "GENERAL TIPS" .IX Header "GENERAL TIPS" The first time a package is backported for any particular Debian release, you will have to pass the \-\-new option to dgit. .SH "TERMINOLOGY" .IX Header "TERMINOLOGY" Let the \fImaster\fR branch contain the packaging history uploaded to Debian unstable, and the \fIbuster-bpo\fR branch be where you prepare your uploads to the \fBbuster-backports\fR suite. .PP A \fBmerging\fR backports workflow means that each time an upload migrates to Debian testing and you want to prepare an upload to \&\fBbuster-backports\fR, you do something like this: .Sp .Vb 6 \& % git checkout buster\-bpo \& % git merge master \& % dch \-\-bpo \& % # any other changes needed for backporting \& % git commit \-a \& % # try a build .Ve .PP A \fBrebasing\fR backports workflow means that you throw away the history of the \fIbuster-bpo\fR branch each time a new version migrates to Debian testing, something equivalent to this: .Sp .Vb 5 \& % git checkout \-B buster\-bpo master \& % dch \-\-bpo \& % # any other changes needed for backporting \& % git commit \-a \& % # try a build .Ve .PP If you use a merging backports workflow, your changelog contains entries for each previous upload to \fBbuster-backports\fR; in a rebasing workflow, it contains only the latest. .SH "CHOOSING BETWEEN THE TWO WORKFLOWS" .IX Header "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 \fB*\-backports\fR suites. .PP 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. .SH "TIPS FOR A MERGING WORKFLOW" .IX Header "TIPS FOR A MERGING WORKFLOW" .SS "Use dgit's branches" .IX Subsection "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. .PP You would use .Sp .Vb 1 \& % dgit clone foo bullseye .Ve .PP for a new backport of package 'foo' to \fBbuster-backports\fR, and then .Sp .Vb 2 \& % dgit fetch bullseye \& % git merge dgit/dgit/bullseye .Ve .PP when new versions migrate to Debian testing. .SH "TIPS FOR A REBASING WORKFLOW" .IX Header "TIPS FOR A REBASING WORKFLOW" .SS "Use dgit's branches" .IX Subsection "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 .Sp .Vb 3 \& % dgit fetch bullseye \& % git checkout \-B buster\-bpo dgit/dgit/bullseye \& % # use git\-cherry\-pick(1) to (re)apply any needed backporting fixes .Ve .SS "Overwriting" .IX Subsection "Overwriting" \&\fBdgit push\fR 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. .PP 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 \&\fBbuster-backports\fR you wish to overwrite. .PP Suppose that the last upload to \fBbuster-backports\fR was versioned \&\fI1.2.2\-1~bpo10+1\fR and you have now prepared \fI1.2.3\-1~bpo10+1\fR for upload. When you \fBdgit push\fR, you will need to pass \&\fI\-\-overwrite=1.2.2\-1~bpo10+1\fR. .PP Alternatively, you can perform the pseudomerge that \fI\-\-overwrite\fR would have done yourself: .Sp .Vb 3 \& % dgit fetch buster\-backports \& % git merge \-s ours dgit/dgit/buster\-backports \& % dgit push\-source .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBdgit\fR\|(1), \fBdgit\fR\|(7), https://backports.debian.org/ .SH "AUTHOR" .IX Header "AUTHOR" This manpage was written and is maintained by Sean Whitton .