1 # SOME DESCRIPTIVE TITLE
2 # Copyright (C) YEAR Free Software Foundation, Inc.
3 # This file is distributed under the same license as the PACKAGE package.
4 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
9 "Project-Id-Version: PACKAGE VERSION\n"
10 "POT-Creation-Date: 2018-10-04 01:04+0100\n"
11 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
12 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
13 "Language-Team: LANGUAGE <LL@li.org>\n"
16 "Content-Type: text/plain; charset=UTF-8\n"
17 "Content-Transfer-Encoding: 8bit\n"
20 #: ../dgit.1:3 ../dgit.7:2 ../dgit-user.7.pod:1 ../dgit-nmu-simple.7.pod:1
21 #: ../dgit-maint-native.7.pod:1 ../dgit-maint-merge.7.pod:1
22 #: ../dgit-maint-gbp.7.pod:1 ../dgit-maint-debrebase.7.pod:1
23 #: ../dgit-downstream-dsc.7.pod:1 ../dgit-sponsorship.7.pod:1
24 #: ../git-debrebase.1.pod:1 ../git-debrebase.5.pod:1
30 #: ../dgit.1:286 ../dgit-maint-merge.7.pod:446
36 #: ../dgit.1:287 ../dgit-maint-merge.7.pod:450
42 #: ../dgit.1:288 ../dgit-maint-merge.7.pod:455
48 #: ../dgit.1:1394 ../dgit.7:23 ../dgit-user.7.pod:447
49 #: ../dgit-nmu-simple.7.pod:137 ../dgit-maint-native.7.pod:126
50 #: ../dgit-maint-merge.7.pod:491 ../dgit-maint-gbp.7.pod:136
51 #: ../dgit-maint-debrebase.7.pod:722 ../dgit-downstream-dsc.7.pod:352
52 #: ../dgit-sponsorship.7.pod:321 ../git-debrebase.1.pod:601
53 #: ../git-debrebase.5.pod:678
59 #: ../dgit-user.7.pod:5 ../dgit-maint-native.7.pod:5
60 #: ../dgit-maint-merge.7.pod:5 ../dgit-maint-gbp.7.pod:5
61 #: ../dgit-maint-debrebase.7.pod:5 ../dgit-downstream-dsc.7.pod:5
62 #: ../git-debrebase.1.pod:10 ../git-debrebase.5.pod:5
67 #: ../dgit-user.7.pod:449 ../dgit-maint-native.7.pod:128
68 #: ../dgit-maint-merge.7.pod:493 ../dgit-maint-gbp.7.pod:138
69 msgid "dgit(1), dgit(7)"
73 #: ../dgit-maint-native.7.pod:107 ../dgit-maint-merge.7.pod:484
81 #: ../dgit-maint-merge.7.pod:3
83 "dgit - tutorial for package maintainers, using a workflow centered around "
88 #: ../dgit-maint-merge.7.pod:7
90 "This document describes elements of a workflow for maintaining a non-native "
91 "Debian package using B<dgit>. The workflow makes the following opinionated "
96 #: ../dgit-maint-merge.7.pod:15
98 "Git histories should be the non-linear histories produced by git-merge(1), "
99 "preserving all information about divergent development that was later "
104 #: ../dgit-maint-merge.7.pod:21
106 "Maintaining convenient and powerful git workflows takes priority over the "
107 "usefulness of the raw Debian source package. The Debian archive is thought "
108 "of as an output format."
112 #: ../dgit-maint-merge.7.pod:25
114 "For example, we don't spend time curating a series of quilt patches. "
115 "However, in straightforward cases, the information such a series would "
116 "contain is readily available from B<dgit-repos>."
120 #: ../dgit-maint-merge.7.pod:33
122 "It is more important to have the Debian package's git history be a "
123 "descendent of upstream's git history than to use exactly the orig.tar that "
124 "upstream makes available for download."
128 #: ../dgit-maint-merge.7.pod:39
130 "This workflow is less suitable for some packages. When the Debian delta "
131 "contains multiple pieces which interact, or which you aren't going to be "
132 "able to upstream soon, it might be preferable to maintain the delta as a "
133 "rebasing patch series. For such a workflow see for example dgit-maint-"
134 "debrebase(7) and dgit-maint-gbp(7)."
138 #: ../dgit-maint-merge.7.pod:47 ../dgit-maint-debrebase.7.pod:61
139 msgid "INITIAL DEBIANISATION"
143 #: ../dgit-maint-merge.7.pod:49 ../dgit-maint-debrebase.7.pod:63
145 "This section explains how to start using this workflow with a new package. "
146 "It should be skipped when converting an existing package to this workflow."
150 #: ../dgit-maint-merge.7.pod:53 ../dgit-maint-merge.7.pod:335
151 #: ../dgit-maint-merge.7.pod:408 ../dgit-maint-debrebase.7.pod:67
152 #: ../dgit-maint-debrebase.7.pod:321
153 msgid "When upstream tags releases in git"
157 #: ../dgit-maint-merge.7.pod:55 ../dgit-maint-debrebase.7.pod:69
159 "Suppose that the latest stable upstream release is 1.2.2, and this has been "
160 "tagged '1.2.2' by upstream."
164 #: ../dgit-maint-merge.7.pod:60 ../dgit-maint-debrebase.7.pod:74
167 " % git clone -oupstream https://some.upstream/foo.git\n"
169 " % git verify-tag 1.2.2\n"
170 " % git reset --hard 1.2.2\n"
171 " % git branch --unset-upstream\n"
176 #: ../dgit-maint-merge.7.pod:68
178 "The final command detaches your master branch from the upstream remote, so "
179 "that git doesn't try to push anything there, or merge unreleased upstream "
180 "commits. If you want to maintain a copy of your packaging branch on B<salsa."
181 "debian.org> in addition to B<dgit-repos>, you can do something like this:"
185 #: ../dgit-maint-merge.7.pod:76 ../dgit-maint-debrebase.7.pod:90
188 " % git remote add -f origin salsa.debian.org:Debian/foo.git\n"
189 " % git push --follow-tags -u origin master\n"
194 #: ../dgit-maint-merge.7.pod:81
196 "Now go ahead and Debianise your package. Just make commits on the master "
197 "branch, adding things in the I<debian/> directory. If you need to patch the "
198 "upstream source, just make commits that change files outside of the I<debian/"
199 "> directory. It is best to separate commits that touch I<debian/> from "
200 "commits that touch upstream source, so that the latter can be cherry-picked "
205 #: ../dgit-maint-merge.7.pod:88
207 "Note that there is no need to maintain a separate 'upstream' branch, unless "
208 "you also happen to be involved in upstream development. We work with "
209 "upstream tags rather than any branches, except when forwarding patches (see "
210 "FORWARDING PATCHES UPSTREAM, below)."
214 #: ../dgit-maint-merge.7.pod:93 ../dgit-maint-debrebase.7.pod:102
215 msgid "Finally, you need an orig tarball:"
219 #: ../dgit-maint-merge.7.pod:97 ../dgit-maint-merge.7.pod:402
220 #: ../dgit-maint-debrebase.7.pod:106 ../dgit-maint-debrebase.7.pod:383
228 #: ../dgit-maint-merge.7.pod:101 ../dgit-maint-debrebase.7.pod:110
229 msgid "See git-deborig(1) if this fails."
233 #: ../dgit-maint-merge.7.pod:103 ../dgit-maint-debrebase.7.pod:112
235 "This tarball is ephemeral and easily regenerated, so we don't commit it "
236 "anywhere (e.g. with tools like pristine-tar(1))."
240 #: ../dgit-maint-merge.7.pod:106
241 msgid "Verifying upstream's tarball releases"
245 #: ../dgit-maint-merge.7.pod:110
247 "It can be a good idea to compare upstream's released tarballs with the "
248 "release tags, at least for the first upload of the package. If they are "
249 "different, you might need to add some additional steps to your I<debian/"
250 "rules>, such as running autotools."
254 #: ../dgit-maint-merge.7.pod:115
256 "A convenient way to perform this check is to import the tarball as described "
257 "in the following section, using a different value for 'upstream-tag', and "
258 "then use git-diff(1) to compare the imported tarball to the release tag. If "
259 "they are the same, you can use upstream's tarball instead of running git-"
264 #: ../dgit-maint-merge.7.pod:123 ../dgit-maint-merge.7.pod:343
265 #: ../dgit-maint-merge.7.pod:433 ../dgit-maint-debrebase.7.pod:137
266 #: ../dgit-maint-debrebase.7.pod:329
267 msgid "When upstream releases only tarballs"
271 #: ../dgit-maint-merge.7.pod:125
273 "We need a virtual upstream branch with virtual release tags. gbp-import-"
274 "orig(1) can manage this for us. To begin"
278 #: ../dgit-maint-merge.7.pod:130 ../dgit-maint-debrebase.7.pod:145
288 #: ../dgit-maint-merge.7.pod:136 ../dgit-maint-debrebase.7.pod:151
289 msgid "Now create I<debian/gbp.conf>:"
293 #: ../dgit-maint-merge.7.pod:140 ../dgit-maint-debrebase.7.pod:155
297 " upstream-branch = upstream\n"
298 " debian-branch = master\n"
299 " upstream-tag = %(version)s\n"
304 #: ../dgit-maint-merge.7.pod:145 ../dgit-maint-debrebase.7.pod:160
307 " sign-tags = True\n"
308 " pristine-tar = False\n"
309 " pristine-tar-commit = False\n"
314 #: ../dgit-maint-merge.7.pod:149 ../dgit-maint-debrebase.7.pod:164
318 " merge-mode = merge\n"
323 #: ../dgit-maint-merge.7.pod:154 ../dgit-maint-debrebase.7.pod:169
324 msgid "gbp-import-orig(1) requires a pre-existing upstream branch:"
328 #: ../dgit-maint-merge.7.pod:158 ../dgit-maint-debrebase.7.pod:173
331 " % git add debian/gbp.conf && git commit -m \"create gbp.conf\"\n"
332 " % git checkout --orphan upstream\n"
334 " % git commit --allow-empty -m \"initial, empty branch for upstream source\"\n"
335 " % git checkout -f master\n"
340 #: ../dgit-maint-merge.7.pod:166 ../dgit-maint-debrebase.7.pod:181
341 msgid "Then we can import the upstream version:"
345 #: ../dgit-maint-merge.7.pod:170 ../dgit-maint-debrebase.7.pod:185
348 " % gbp import-orig --merge-mode=replace ../foo_1.2.2.orig.tar.xz\n"
353 #: ../dgit-maint-merge.7.pod:174 ../dgit-maint-debrebase.7.pod:189
355 "Our upstream branch cannot be pushed to B<dgit-repos>, but since we will "
356 "need it whenever we import a new upstream version, we must push it "
357 "somewhere. The usual choice is B<salsa.debian.org>:"
361 #: ../dgit-maint-merge.7.pod:180 ../dgit-maint-debrebase.7.pod:195
364 " % git remote add -f origin salsa.debian.org:Debian/foo.git\n"
365 " % git push --follow-tags -u origin master upstream\n"
370 #: ../dgit-maint-merge.7.pod:185
372 "You are now ready to proceed as above, making commits to both the upstream "
373 "source and the I<debian/> directory."
377 #: ../dgit-maint-merge.7.pod:188 ../dgit-maint-debrebase.7.pod:207
378 msgid "CONVERTING AN EXISTING PACKAGE"
382 #: ../dgit-maint-merge.7.pod:190 ../dgit-maint-debrebase.7.pod:209
384 "This section explains how to convert an existing Debian package to this "
385 "workflow. It should be skipped when debianising a new package."
389 #: ../dgit-maint-merge.7.pod:193
390 msgid "No existing git history"
394 #: ../dgit-maint-merge.7.pod:197
397 " % dgit clone foo\n"
399 " % git remote add -f upstream https://some.upstream/foo.git\n"
404 #: ../dgit-maint-merge.7.pod:203
405 msgid "Existing git history using another workflow"
409 #: ../dgit-maint-merge.7.pod:205
411 "First, if you don't already have the git history locally, clone it, and "
412 "obtain the corresponding orig.tar from the archive:"
416 #: ../dgit-maint-merge.7.pod:210
419 " % git clone git.debian.org:collab-maint/foo\n"
426 #: ../dgit-maint-merge.7.pod:216
427 msgid "Now dump any existing patch queue:"
431 #: ../dgit-maint-merge.7.pod:220
434 " % git rm -rf debian/patches\n"
435 " % git commit -m \"drop existing quilt patch queue\"\n"
440 #: ../dgit-maint-merge.7.pod:225
441 msgid "Then make new upstream tags available:"
445 #: ../dgit-maint-merge.7.pod:229 ../dgit-maint-debrebase.7.pod:240
448 " % git remote add -f upstream https://some.upstream/foo.git\n"
453 #: ../dgit-maint-merge.7.pod:233
454 msgid "dgit-test dpkg-source-ignores begin"
458 #: ../dgit-maint-merge.7.pod:235
460 "Now you simply need to ensure that your git HEAD is dgit-compatible, i.e., "
461 "it is exactly what you would get if you ran B<dpkg-buildpackage -i'(?:^|/)\\."
462 "git(?:/|$)' -I.git -S> and then unpacked the resultant source package."
466 #: ../dgit-maint-merge.7.pod:240
467 msgid "dgit-test dpkg-source-ignores end"
471 #: ../dgit-maint-merge.7.pod:242 ../dgit-maint-debrebase.7.pod:289
473 "To achieve this, you might need to delete I<debian/source/local-options>. "
474 "One way to have dgit check your progress is to run B<dgit build-source>."
478 #: ../dgit-maint-merge.7.pod:246
480 "The first dgit push will require I<--overwrite>. If this is the first ever "
481 "dgit push of the package, consider passing I<--deliberately-not-fast-"
482 "forward> instead of I<--overwrite>. This avoids introducing a new origin "
483 "commit into your git history. (This origin commit would represent the most "
484 "recent non-dgit upload of the package, but this should already be "
485 "represented in your git history.)"
489 #: ../dgit-maint-merge.7.pod:253
490 msgid "SOURCE PACKAGE CONFIGURATION"
494 #: ../dgit-maint-merge.7.pod:255
495 msgid "debian/source/options"
499 #: ../dgit-maint-merge.7.pod:257
501 "We set some source package options such that dgit can transparently handle "
502 "the \"dropping\" and \"refreshing\" of changes to the upstream source:"
506 #: ../dgit-maint-merge.7.pod:263
509 " single-debian-patch\n"
515 #: ../dgit-maint-merge.7.pod:268
517 "You don't need to create this file if you are using the version 1.0 source "
522 #: ../dgit-maint-merge.7.pod:271
523 msgid "Sample text for debian/source/patch-header"
527 #: ../dgit-maint-merge.7.pod:273
529 "It is a good idea to explain how a user can obtain a breakdown of the "
530 "changes to the upstream source:"
534 #: ../dgit-maint-merge.7.pod:278
536 "The Debian packaging of foo is maintained in git, using the merging workflow "
537 "described in dgit-maint-merge(7). There isn't a patch queue that can be "
538 "represented as a quilt series."
542 #: ../dgit-maint-merge.7.pod:282
544 "A detailed breakdown of the changes is available from their canonical "
545 "representation - git commits in the packaging repository. For example, to "
546 "see the changes made by the Debian maintainer in the first upload of "
547 "upstream version 1.2.3, you could use:"
551 #: ../dgit-maint-merge.7.pod:290
554 " % git clone https://git.dgit.debian.org/foo\n"
556 " % git log --oneline 1.2.3..debian/1.2.3-1 -- . ':!debian'\n"
561 #: ../dgit-maint-merge.7.pod:296
563 "(If you have dgit, use `dgit clone foo`, rather than plain `git clone`.)"
567 #: ../dgit-maint-merge.7.pod:299
568 msgid "A single combined diff, containing all the changes, follows."
572 #: ../dgit-maint-merge.7.pod:303
574 "If you are using the version 1.0 source package format, this text should be "
575 "added to README.source instead. The version 1.0 source package format "
576 "ignores debian/source/patch-header."
580 #: ../dgit-maint-merge.7.pod:307
582 "If you're using the version 3.0 (quilt) source package format, you could add "
583 "this text to README.source instead of debian/source/patch-header, but this "
584 "might distract from more important information present in README.source."
588 #: ../dgit-maint-merge.7.pod:312 ../dgit-maint-debrebase.7.pod:436
589 msgid "BUILDING AND UPLOADING"
593 #: ../dgit-maint-merge.7.pod:314
595 "Use B<dgit build>, B<dgit sbuild>, B<dgit pbuilder>, B<dgit cowbuilder>, "
596 "B<dgit push-source>, and B<dgit push> as detailed in dgit(1). If any "
597 "command fails, dgit will provide a carefully-worded error message explaining "
598 "what you should do. If it's not clear, file a bug against dgit. Remember "
599 "to pass I<--new> for the first upload."
603 #: ../dgit-maint-merge.7.pod:320
605 "As an alternative to B<dgit build> and friends, you can use a tool like "
606 "gitpkg(1). This works because like dgit, gitpkg(1) enforces that HEAD has "
607 "exactly the contents of the source package. gitpkg(1) is highly "
608 "configurable, and one dgit user reports using it to produce and test "
609 "multiple source packages, from different branches corresponding to each of "
610 "the current Debian suites."
614 #: ../dgit-maint-merge.7.pod:327
616 "If you want to skip dgit's checks while iterating on a problem with the "
617 "package build (for example, you don't want to commit your changes to git), "
618 "you can just run dpkg-buildpackage(1) or debuild(1) instead."
622 #: ../dgit-maint-merge.7.pod:331
623 msgid "NEW UPSTREAM RELEASES"
627 #: ../dgit-maint-merge.7.pod:333 ../dgit-maint-debrebase.7.pod:319
628 msgid "Obtaining the release"
632 #: ../dgit-maint-merge.7.pod:339 ../dgit-maint-debrebase.7.pod:325
635 " % git remote update\n"
640 #: ../dgit-maint-merge.7.pod:345 ../dgit-maint-debrebase.7.pod:331
642 "You will need the I<debian/gbp.conf> from \"When upstream releases only "
643 "tarballs\", above. You will also need your upstream branch. Above, we "
644 "pushed this to B<salsa.debian.org>. You will need to clone or fetch from "
645 "there, instead of relying on B<dgit clone>/B<dgit fetch> alone."
649 #: ../dgit-maint-merge.7.pod:350 ../dgit-maint-debrebase.7.pod:336
654 #: ../dgit-maint-merge.7.pod:354 ../dgit-maint-debrebase.7.pod:340
657 " % gbp import-orig --no-merge ../foo_1.2.3.orig.tar.xz\n"
662 #: ../dgit-maint-merge.7.pod:358 ../dgit-maint-debrebase.7.pod:344
663 msgid "or if you have a working watch file"
667 #: ../dgit-maint-merge.7.pod:362 ../dgit-maint-debrebase.7.pod:348
670 " % gbp import-orig --no-merge --uscan\n"
675 #: ../dgit-maint-merge.7.pod:366
676 msgid "Reviewing & merging the release"
680 #: ../dgit-maint-merge.7.pod:368
682 "It's a good idea to preview the merge of the new upstream release. First, "
683 "just check for any new or deleted files that may need accounting for in your "
688 #: ../dgit-maint-merge.7.pod:374
691 " % git diff --stat master..1.2.3 -- . ':!debian'\n"
696 #: ../dgit-maint-merge.7.pod:378
697 msgid "You can then review the full merge diff:"
701 #: ../dgit-maint-merge.7.pod:382
704 " % git merge-tree `git merge-base master 1.2.3` master 1.2.3 | $PAGER\n"
709 #: ../dgit-maint-merge.7.pod:386
710 msgid "Once you're satisfied with what will be merged, update your package:"
714 #: ../dgit-maint-merge.7.pod:390
717 " % git merge 1.2.3\n"
718 " % dch -v1.2.3-1 New upstream release.\n"
719 " % git add debian/changelog && git commit -m changelog\n"
724 #: ../dgit-maint-merge.7.pod:396 ../dgit-maint-debrebase.7.pod:377
726 "If you obtained a tarball from upstream, you are ready to try a build. If "
727 "you merged a git tag from upstream, you will first need to generate a "
732 #: ../dgit-maint-merge.7.pod:406 ../dgit-maint-debrebase.7.pod:461
733 msgid "HANDLING DFSG-NON-FREE MATERIAL"
737 #: ../dgit-maint-merge.7.pod:410
738 msgid "We create a DFSG-clean tag to merge to master:"
742 #: ../dgit-maint-merge.7.pod:414
745 " % git checkout -b pre-dfsg 1.2.3\n"
746 " % git rm evil.bin\n"
747 " % git commit -m \"upstream version 1.2.3 DFSG-cleaned\"\n"
748 " % git tag -s 1.2.3+dfsg\n"
749 " % git checkout master\n"
750 " % git branch -D pre-dfsg\n"
755 #: ../dgit-maint-merge.7.pod:423
757 "Before merging the new 1.2.3+dfsg tag to master, you should first determine "
758 "whether it would be legally dangerous for the non-free material to be "
759 "publicly accessible in the git history on B<dgit-repos>."
763 #: ../dgit-maint-merge.7.pod:428
765 "If it would be dangerous, there is a big problem; in this case please "
766 "consult your archive administrators (for Debian this is the dgit "
767 "administrator dgit-owner@debian.org and the ftpmasters ftpmaster@ftp-master."
772 #: ../dgit-maint-merge.7.pod:435 ../dgit-maint-debrebase.7.pod:521
774 "The easiest way to handle this is to add a B<Files-Excluded> field to "
775 "I<debian/copyright>, and a B<uversionmangle> setting in I<debian/watch>. "
776 "See uscan(1). Alternatively, see the I<--filter> option detailed in gbp-"
781 #: ../dgit-maint-merge.7.pod:440
782 msgid "FORWARDING PATCHES UPSTREAM"
786 #: ../dgit-maint-merge.7.pod:442
787 msgid "The basic steps are:"
791 #: ../dgit-maint-merge.7.pod:448
792 msgid "Create a new branch based off upstream's master branch."
796 #: ../dgit-maint-merge.7.pod:452
798 "git-cherry-pick(1) commits from your master branch onto your new branch."
802 #: ../dgit-maint-merge.7.pod:457
804 "Push the branch somewhere and ask upstream to merge it, or use git-format-"
805 "patch(1) or git-request-pull(1)."
809 #: ../dgit-maint-merge.7.pod:462
810 msgid "For example (and it is only an example):"
814 #: ../dgit-maint-merge.7.pod:466
817 " % # fork foo.git on GitHub\n"
818 " % git remote add -f fork git@github.com:spwhitton/foo.git\n"
819 " % git checkout -b fix-error upstream/master\n"
820 " % git config branch.fix-error.pushRemote fork\n"
821 " % git cherry-pick master^2\n"
823 " % # submit pull request on GitHub\n"
828 #: ../dgit-maint-merge.7.pod:476
830 "Note that when you merge an upstream release containing your forwarded "
831 "patches, git and dgit will transparently handle \"dropping\" the patches "
832 "that have been forwarded, \"retaining\" the ones that haven't."
836 #: ../dgit-maint-merge.7.pod:480 ../dgit-maint-gbp.7.pod:130
837 #: ../dgit-maint-debrebase.7.pod:526
838 msgid "INCORPORATING NMUS"
842 #: ../dgit-maint-merge.7.pod:488
844 "Alternatively, you can apply the NMU diff to your repository. The next push "
845 "will then require I<--overwrite>."
849 #: ../dgit-maint-merge.7.pod:495 ../dgit-maint-gbp.7.pod:140
850 #: ../dgit-maint-debrebase.7.pod:726
855 #: ../dgit-maint-merge.7.pod:497 ../dgit-maint-debrebase.7.pod:728
857 "This tutorial was written and is maintained by Sean Whitton "
858 "<spwhitton@spwhitton.name>. It contains contributions from other dgit "
859 "contributors too - see the dgit copyright file."