Bug#840153: Should have various tutorial manpages

[Sean Whitton]

On Thu, Oct 27, 2016 at 02:38:47PM +0100, Ian Jackson wrote:
> > After the docs upload, it might be good to do some advertising.
> > Misc. Developer News at least.
> 
> I was intending another d-d-a posting.

Great.  Both the patches-unapplied and the tutorials should attract
interest.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#840153: Should have various tutorial manpages

[Ian Jackson]

Sean Whitton writes ("Re: Bug#840153: Should have various tutorial manpages"):
> On Thu, Oct 27, 2016 at 10:29:02AM +0100, Ian Jackson wrote:
> > But, I'll have whatever you can produce in a week or so.  I think
> > 2.8 (!) may migrate and then I'll be wanting to upload a new version
> > with better docs.
> 
> Okay.  I'm planning to look at this on Saturday.

Great.

During lunch I wrote dgit-sponsorship(7), now pushed to my
wip.tutorials branch.

> After the docs upload, it might be good to do some advertising.
> Misc. Developer News at least.

I was intending another d-d-a posting.

Ian.

-- 
Ian Jackson <ijack...@chiark.greenend.org.uk>   These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.

Bug#840153: Should have various tutorial manpages

[Sean Whitton]

On Thu, Oct 27, 2016 at 10:29:02AM +0100, Ian Jackson wrote:
> But, I'll have whatever you can produce in a week or so.  I think
> 2.8 (!) may migrate and then I'll be wanting to upload a new version
> with better docs.

Okay.  I'm planning to look at this on Saturday.

After the docs upload, it might be good to do some advertising.
Misc. Developer News at least.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#840153: Should have various tutorial manpages

[Ian Jackson]

Sean Whitton writes ("Re: Bug#840153: Should have various tutorial manpages"):
> On Thu, Oct 27, 2016 at 01:02:43AM +0100, Ian Jackson wrote:
> > Are you still intending to look into dgit-maint-gbp(7) ?
> 
> Would you prefer to release a short manpage with a few remarks, or wait
> until I've got something longer?
> 
> I've thought about what I'd put in it, and there isn't much because I've
> only done two or three uploads with dgit and gbp.  I was thinking I'd be
> able to write something longer in a few months (or maybe not, if there
> isn't much to say).

I'm hoping there's not much to say...  dgit-nmu-simple came out fairly
short.

But, I'll have whatever you can produce in a week or so.  I think
2.8 (!) may migrate and then I'll be wanting to upload a new version
with better docs.

Thanks for all your help.

Ian.

-- 
Ian Jackson <ijack...@chiark.greenend.org.uk>   These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.

Bug#840153: Should have various tutorial manpages

[Sean Whitton]

Hello Ian,

On Thu, Oct 27, 2016 at 01:02:43AM +0100, Ian Jackson wrote:
> FYI, I have been working on dgit-user(7) and dgit-nmu-simple(7).
> I think they're mostly done.

I'll take a look!

> dgit-sponsorship(7) is next on my list.

That would be great.  I spend a lot of time on d-mentors so I suspect
I'll have some things to add ;)

> Are you still intending to look into dgit-maint-gbp(7) ?

Would you prefer to release a short manpage with a few remarks, or wait
until I've got something longer?

I've thought about what I'd put in it, and there isn't much because I've
only done two or three uploads with dgit and gbp.  I was thinking I'd be
able to write something longer in a few months (or maybe not, if there
isn't much to say).

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#840153: Should have various tutorial manpages

[Ian Jackson]

FYI, I have been working on dgit-user(7) and dgit-nmu-simple(7).
I think they're mostly done.

If you would like to review what I have, you can find them
here
  
http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=tree;h=refs/heads/wip.tutorials;hb=refs/heads/wip.tutorials
  git://git.chiark.greenend.org.uk/~ianmdlvl/dgit.git#wip.tutorials
(rebasing branch).

dgit-sponsorship(7) is next on my list.

Are you still intending to look into dgit-maint-gbp(7) ?

Regards,
Ian.

-- 
Ian Jackson    These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.

Bug#840153: Should have various tutorial manpages

[Ian Jackson]

Sean Whitton writes ("Re: Bug#840153: Should have various tutorial manpages"):
> Yes, just my habit of hitting M-q in Emacs.
> 
> Are the semantic newlines for the benefit of someone editing the .pod,
> or for the benefit of a future natural-language parsing computer?  I
> think I see what you did, but I don't yet see the benefit.

The point of the semantic newlines is to reduce noise in diffs and
make editing easier.

I realise now that I send you a link to a randomly unrelated article !
Try this one instead:

  http://rhodesmill.org/brandon/2012/one-sentence-per-line/

> I think it would be best if you just made a commit on your master branch
> just adding a new line.  I can prepare a patch if you really want...

I have the patch, thanks :-).

Regards,
Ian.

-- 
Ian Jackson <ijack...@chiark.greenend.org.uk>   These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.

Bug#840153: Should have various tutorial manpages

[Sean Whitton]

Dear Ian,

On Fri, Oct 21, 2016 at 01:28:14AM +0100, Ian Jackson wrote:
> All I saw in your commit message was the rewrapping.  But now I look
> at it again there is an additional blank line too.
> 
> The rewrapping replaces the semantic newlines (which I used when I
> rewrote that paragraph) with what looks like the result of an
> automatic wordwrap algorithm.

Yes, just my habit of hitting M-q in Emacs.

Are the semantic newlines for the benefit of someone editing the .pod,
or for the benefit of a future natural-language parsing computer?  I
think I see what you did, but I don't yet see the benefit.

I think it would be best if you just made a commit on your master branch
just adding a new line.  I can prepare a patch if you really want...

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#840153: Should have various tutorial manpages

[Ian Jackson]

Ian Jackson writes ("Re: Bug#840153: Should have various tutorial manpages"):
> I don't mind the additional paragraph break.

Ie, like this.  The output of pod2man | man -l is the same.

Ian.

>From de9555e90291fcfa3d374bc02d1a5fff8a3f7617 Mon Sep 17 00:00:00 2001
From: Sean Whitton <spwhit...@spwhitton.name>
Date: Wed, 19 Oct 2016 19:59:34 -0700
Subject: [PATCH] dgit-maint-merge(7): spacing

Signed-off-by: Ian Jackson <ijack...@chiark.greenend.org.uk>
---
 dgit-maint-merge.7.pod | 1 +
 1 file changed, 1 insertion(+)

diff --git a/dgit-maint-merge.7.pod b/dgit-maint-merge.7.pod
index 2900492..f785af7 100644
--- a/dgit-maint-merge.7.pod
+++ b/dgit-maint-merge.7.pod
@@ -314,6 +314,7 @@ Before merging the new 1.2.3+dfsg tag to master, you should 
first
 determine whether it would be legally dangerous for the non-free
 material to be publicly accessible in the git history on
 B.
+
 If it would be dangerous, there is a big problem;
 in this case please consult your archive administrators
 (for Debian this is the dgit administrator dgit-ow...@debian.org
-- 
2.9.3



-- 
Ian Jackson <ijack...@chiark.greenend.org.uk>   These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.

Bug#840153: Should have various tutorial manpages

[Ian Jackson]

Sean Whitton writes ("Bug#840153: Should have various tutorial manpages"):
> control: tag -1 -patch
> ^ since no patch for the other manpages listed in the first message

Thanks, yes.

> On Thu, Oct 20, 2016 at 08:38:48PM +0100, Ian Jackson wrote:
> > As for your final patch "dgit-maint-merge(7): spacing".  Is there a
> > reason in a .pod file not to use semantic whitespace ?
> > perlpod(1) suggests not AFAICT.
> 
> My commit message was poor.  I should have written "split into two
> paragraphs".  Does that make sense of the change?

Oh.  Yes, well, somewhat.

> I don't understand how a paragraph split can have anything to do with
> semantic whitespace -- unless there is already a paragraph break without
> the blank line, and the commit has no effect on the manpage output?

All I saw in your commit message was the rewrapping.  But now I look
at it again there is an additional blank line too.

The rewrapping replaces the semantic newlines (which I used when I
rewrote that paragraph) with what looks like the result of an
automatic wordwrap algorithm.

I don't mind the additional paragraph break.  I do rather mind the
rewrapping (which is just pointless noise in the diff), but I will
tolerate it if you convince me you have understood what I mean by
"semantic newlines" and explain that you are doing this deliberately
:-).  After all I don't want to have a stupid argument about
whitespace.

Ian.

-- 
Ian Jackson <ijack...@chiark.greenend.org.uk>   These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.

Bug#840153: Should have various tutorial manpages

[Sean Whitton]

control: tag -1 -patch
^ since no patch for the other manpages listed in the first message

Hello,

On Thu, Oct 20, 2016 at 08:38:48PM +0100, Ian Jackson wrote:
> As for your final patch "dgit-maint-merge(7): spacing".  Is there a
> reason in a .pod file not to use semantic whitespace ?
> perlpod(1) suggests not AFAICT.

My commit message was poor.  I should have written "split into two
paragraphs".  Does that make sense of the change?

I don't understand how a paragraph split can have anything to do with
semantic whitespace -- unless there is already a paragraph break without
the blank line, and the commit has no effect on the manpage output?

-- 
Sean Whitton

Bug#840153: Should have various tutorial manpages

[Ian Jackson]

Sean Whitton writes ("Bug#840153: Should have various tutorial manpages"):
> On Thu, Oct 20, 2016 at 01:37:46AM +0100, Ian Jackson wrote:
> > You might want to mention that if you do this check, you might as well
> > use the upstream tarball rather than `git-archive'.
> 
> Done: https://git.spwhitton.name/dgit -b wip.manpages

Great.  I've incorporated all but the last of those into my master (by
rebasing) and they'll be in whatever is the next upload.  Again, I'm
hoping not to do another upload until I get a testing propagation but
people will keep finding bugs that can't wait...

As for your final patch "dgit-maint-merge(7): spacing".  Is there a
reason in a .pod file not to use semantic whitespace ?
perlpod(1) suggests not AFAICT.

You may not have heard of "semantic whitespace".  I only came across
the idea myself quite recently.  Read this:
  http://blog.aaronballman.com/2011/05/semantic-whitespace/

I was instantly convinced.

Regards,
Ian.

-- 
Ian Jackson <ijack...@chiark.greenend.org.uk>   These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.

Bug#840153: Should have various tutorial manpages

[Sean Whitton]

Hello Ian,

On Thu, Oct 20, 2016 at 01:37:46AM +0100, Ian Jackson wrote:
> Sean Whitton writes ("Re: Bug#840153: Should have various tutorial manpages"):
> > On Wed, Oct 19, 2016 at 09:31:28PM +0100, Ian Jackson wrote:
> > I'll ensure that I don't commit stuff that doesn't build, now that I
> > know I can submit patches by publishing a branch somewhere.  The patches
> > were ordered the way they were so that I could easily --amend the patch
> > that adds the manpage.
> 
> Aha.  Are you aware of
>   git rebase -i --autosquash
> ?

Ah, cool.  So that's what those Magit[1] options are for.

> > I don't understand the two non-trivial changes you've made to the
> > text of the manpage.  I hope you can explain further.
> 
> I think you may mean you don't agree :-).

At least (2) was a lack of understanding!

> Sure.  Would you care to add that as a commit on top of my branch ?  I
> don't really mind flail in the git history if the intervening commits
> pass the tests and don't contain garbage.
> 
> You might want to mention that if you do this check, you might as well
> use the upstream tarball rather than `git-archive'.

Done: https://git.spwhitton.name/dgit -b wip.manpages

> > (2) the removal of the advice to use --squash:
> > 
> > Could you explain why you think this was bad advice?  It ensures that
> > the bad refs are *not* pushed to dgit-repos.  I agree with your addition
> > of contact details for the relevant archive administrators.
> 
> I don't think this is a sufficiently robust way of responding to the
> discovery of harmful and/or legally dangerous objects in a public git
> history.

Yes, you're right.  Even if someone wanted to use --squash, the
blacklisting would need to be in place to prevent accidents later, so
they might as well just contact the relevant administrators.

[1] http://magit.vc/

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#840153: Should have various tutorial manpages

[Ian Jackson]

Sean Whitton writes ("Re: Bug#840153: Should have various tutorial manpages"):
> On Wed, Oct 19, 2016 at 09:31:28PM +0100, Ian Jackson wrote:
> I'll ensure that I don't commit stuff that doesn't build, now that I
> know I can submit patches by publishing a branch somewhere.  The patches
> were ordered the way they were so that I could easily --amend the patch
> that adds the manpage.

Aha.  Are you aware of
  git rebase -i --autosquash
?

> I don't understand the two non-trivial changes you've made to the text
> of the manpage.  I hope you can explain further.

I think you may mean you don't agree :-).

> (1) the addition to the "initial debianisation" section:
> 
> I don't think this workflow should explicitly recommend going anywhere
> near upstream's tarballs, except in the case where upstream doesn't use
> git.
> 
> A package maintainer might have a good reason to do a consistency check
> that upstream's released tarballs match their signed tags.  To my mind,
> this is akin to all the other testing that a package maintainer
> performs, such as installing it and seeing if it segfaults.
> 
> However, the way that you have written the text suggests that that check
> is an integral part of using the merge workflow.  I don't think it
> should be.  Although it's true that you _can_ use upstream's tarball if
> it is identical to the tag, there is absolutely no need to do so.  This
> is the kind of busywork we're trying to avoid.  Just `git archive` and
> forget about it.  The gbp documentation, too, discusses the case where
> you "don't care" about the tarballs upstream releases.
> 
> I like the pointer to "When upstream releases only tarballs" for the
> purposes of performing this consistency check, though.  So I'd like to
> suggest deleting your "When upstream tags releases in git and releases
> identical tarballs" section, and instead appending the following text to
> the "When upstream tags releases in git" section:
> 
> (It is often a good idea to confirm that upstream's released
> tarballs match the release tags.  A convenient way to do this is to
> import the tarball as described in "When upstream releases only
> tarballs", using a different value for 'upstream-tag', and then use
> git-diff(1).)

Sure.  Would you care to add that as a commit on top of my branch ?  I
don't really mind flail in the git history if the intervening commits
pass the tests and don't contain garbage.

You might want to mention that if you do this check, you might as well
use the upstream tarball rather than `git-archive'.

> (2) the removal of the advice to use --squash:
> 
> Could you explain why you think this was bad advice?  It ensures that
> the bad refs are *not* pushed to dgit-repos.  I agree with your addition
> of contact details for the relevant archive administrators.

I don't think this is a sufficiently robust way of responding to the
discovery of harmful and/or legally dangerous objects in a public git
history.

If the discoverer takes your approach, these objects will remain on
their own computer, which is itself dangerous.

The objects are very likely to make their way onto the dgit git server
at some point, if only because someone binds the upstream history into
the dgit history (which one might well do without looking at it
particularly closely).  Or because someone doesn't notice some time
when they are preparing a new upstream version.

To prevent this, at the very least, the dgit git server should be
configured to reject the bad objects.  This requires administrator
intervention.

The same objects are probably already on alioth.  So someone needs to
talk to the alioth admins perhaps.

Furthermore, if there _are_ such legally dangerous in a project's git
history, then the project's upstream will probably want to know about
it too!  Ideally the whole project's git history would be rewritten by
everyone in a coordinated way, and everyone would know to wipe the bad
data from their computers.

Done properly, this all gets quite complicated, and perhaps political,
and the problem might need to not be broadcasted widely, as well.  It
might involve taking urgent legal advice.

I really don't think we as a project could leave one of our individual
contributors to deal with such a problem by themselves, as best they
can.  That would be a doing them, and everyone else, a gross
disservice.

Note that by "legally dangerous", "harmful", or whatever we are
talking about data that might get you locked up or harassed or
something.  Examples would be child sexual abuse images, bomb-making
manuals, military or diplomatic secrets, etc.

We don't mean things where the copyright licence is unclear, missing,
or widely breached, unless the copyrightholder is pursuing it or
likely to do so. 

Bug#840153: Should have various tutorial manpages

[Sean Whitton]

Hello Ian,

On Wed, Oct 19, 2016 at 09:31:28PM +0100, Ian Jackson wrote:
> Sean Whitton writes ("Bug#840153: Should have various tutorial manpages"):
> > control: tag -1 +patch
> > 
> > Please find attached git-am(1)-amenable patches adding some pod2man
> > infrastructure, and dgit-maint-merge(7).
> 
> Thanks!  I really like your new manpage.

Thanks for responding to my patch submission!

> And you should add it to the Makefile in the same commit as you add
> the file, or you create a commit that doesn't build.

> BTW I'm just as happy with git branch on a server as I am with git-am
> patches.

I'll ensure that I don't commit stuff that doesn't build, now that I
know I can submit patches by publishing a branch somewhere.  The patches
were ordered the way they were so that I could easily --amend the patch
that adds the manpage.

> I have also made a few changes to the manpage, which I hope you will
> approve of.

I don't understand the two non-trivial changes you've made to the text
of the manpage.  I hope you can explain further.

(1) the addition to the "initial debianisation" section:

I don't think this workflow should explicitly recommend going anywhere
near upstream's tarballs, except in the case where upstream doesn't use
git.

A package maintainer might have a good reason to do a consistency check
that upstream's released tarballs match their signed tags.  To my mind,
this is akin to all the other testing that a package maintainer
performs, such as installing it and seeing if it segfaults.

However, the way that you have written the text suggests that that check
is an integral part of using the merge workflow.  I don't think it
should be.  Although it's true that you _can_ use upstream's tarball if
it is identical to the tag, there is absolutely no need to do so.  This
is the kind of busywork we're trying to avoid.  Just `git archive` and
forget about it.  The gbp documentation, too, discusses the case where
you "don't care" about the tarballs upstream releases.

I like the pointer to "When upstream releases only tarballs" for the
purposes of performing this consistency check, though.  So I'd like to
suggest deleting your "When upstream tags releases in git and releases
identical tarballs" section, and instead appending the following text to
the "When upstream tags releases in git" section:

(It is often a good idea to confirm that upstream's released
tarballs match the release tags.  A convenient way to do this is to
import the tarball as described in "When upstream releases only
tarballs", using a different value for 'upstream-tag', and then use
git-diff(1).)

(2) the removal of the advice to use --squash:

Could you explain why you think this was bad advice?  It ensures that
the bad refs are *not* pushed to dgit-repos.  I agree with your addition
of contact details for the relevant archive administrators.

> > (I'm keen to retain the authorship information in the actual
> > manpage, but you might not like how I've edited d/copyright, so I
> > made that a separate patch.)
> 
> Right.  I have changed this a bit.  I hope you like it.

All fine.

--
Sean Whitton


signature.asc
Description: PGP signature

Bug#840153: Should have various tutorial manpages

[Ian Jackson]

Sean Whitton writes ("Bug#840153: Should have various tutorial manpages"):
> control: tag -1 +patch
> 
> Please find attached git-am(1)-amenable patches adding some pod2man
> infrastructure, and dgit-maint-merge(7).

Thanks!  I really like your new manpage.

I have fixed up a few things with the build - notably, I thought "make
all" should build the manpage.  And you should add it to the Makefile
in the same commit as you add the file, or you create a commit that
doesn't build.

I have also made a few changes to the manpage, which I hope you will
approve of.

> (I'm keen to retain the authorship information in the actual manpage,
> but you might not like how I've edited d/copyright, so I made that a
> separate patch.)

Right.  I have changed this a bit.  I hope you like it.

Can you take a look at
  
http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=shortlog;h=refs/heads/wip.manpages
aka
  git://git.chiark.greenend.org.uk/~ianmdlvl/dgit.git#wip.manpages
and let me know if you approve ?  If so I will push it to master,
assuming it passes whatever tests I choose to run on it.

(NB that "wip.*" branches in my repos are rewinding and might
disappear.)

BTW I'm just as happy with git branch on a server as I am with git-am
patches.

Regards,
Ian.

-- 
Ian Jackson <ijack...@chiark.greenend.org.uk>   These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.

Bug#840153: Should have various tutorial manpages -- fixed patch submission

[Sean Whitton]

Hello,

On Tue, Oct 18, 2016 at 05:35:37PM -0700, Sean Whitton wrote:
> Please find attached git-am(1)-amenable patches adding some pod2man
> infrastructure, and dgit-maint-merge(7).
> 
> (I'm keen to retain the authorship information in the actual manpage,
> but you might not like how I've edited d/copyright, so I made that a
> separate patch.)

Sorry, screwed up the previous patch submission.  Here are the correct
four patches.

-- 
Sean Whitton
From c91d5c541983977bd7f6f796ce0b39c38bd12c25 Mon Sep 17 00:00:00 2001
From: Sean Whitton 
Date: Tue, 18 Oct 2016 17:20:27 -0700
Subject: [PATCH 1/4] Makefile: build and clean *.7.pod

Signed-off-by: Sean Whitton 
---
 Makefile | 12 ++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index 6fcc9bd..3f071e3 100644
--- a/Makefile
+++ b/Makefile
@@ -33,7 +33,7 @@ txtdocdir=$(prefix)/share/doc/dgit
 
 PROGRAMS=dgit
 MAN1PAGES=dgit.1
-MAN7PAGES=dgit.7
+MAN7PAGES=dgit.7 dgit-maint-merge.7
 TXTDOCS=README.dsc-import
 PERLMODULES=Debian/Dgit.pm
 
@@ -48,7 +48,7 @@ INFRA_PERLMODULES= \
 
 all:
 
-install:	installdirs
+install:	installdirs $(MAN7PAGES)
 	$(INSTALL_PROGRAM) $(PROGRAMS) $(DESTDIR)$(bindir)
 	$(INSTALL_DATA) $(MAN1PAGES) $(DESTDIR)$(man1dir)
 	$(INSTALL_DATA) $(MAN7PAGES) $(DESTDIR)$(man7dir)
@@ -80,3 +80,11 @@ check installcheck:
 
 clean distclean mostlyclean maintainer-clean:
 	rm -rf tests/tmp
+	set -e; for m in $(MAN7PAGES); do \
+		test -e $$m.pod && rm -f $$m; \
+	done
+
+%.7: %.7.pod
+	pod2man --section=7 --date="Debian Project" --center="dgit" \
+		--name=$(subst .7,,$@) \
+		$^ $@
-- 
2.9.3

From 7d9ab53f8b47815a62a4ff4e5c19facd70c57a90 Mon Sep 17 00:00:00 2001
From: Sean Whitton 
Date: Tue, 18 Oct 2016 17:22:49 -0700
Subject: [PATCH 2/4] debian/copyright: add myself

Signed-off-by: Sean Whitton 
---
 debian/copyright | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/debian/copyright b/debian/copyright
index 493b700..88a5e6d 100644
--- a/debian/copyright
+++ b/debian/copyright
@@ -3,6 +3,8 @@ Integration between git and Debian-style archives
 
 Copyright (C)2013-2016 Ian Jackson
 
+dgit-maint-merge.7.pod is copyright (C)2016 Sean Whitton
+
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation, either version 3 of the License, or
-- 
2.9.3

From fdef83c4e1651315bda2fd86781cac136d148156 Mon Sep 17 00:00:00 2001
From: Sean Whitton 
Date: Tue, 18 Oct 2016 17:23:11 -0700
Subject: [PATCH 3/4] Manpage: add dgit-maint-merge.7.pod

Signed-off-by: Sean Whitton 
---
 dgit-maint-merge.7.pod | 365 +
 1 file changed, 365 insertions(+)
 create mode 100644 dgit-maint-merge.7.pod

diff --git a/dgit-maint-merge.7.pod b/dgit-maint-merge.7.pod
new file mode 100644
index 000..d9dcb51
--- /dev/null
+++ b/dgit-maint-merge.7.pod
@@ -0,0 +1,365 @@
+=head1 NAME
+
+dgit - tutorial for package maintainers, using a workflow centered around git-merge(1)
+
+=head1 INTRODUCTION
+
+This document describes elements of a workflow for maintaining a
+non-native Debian package using B.  The workflow makes the
+following opinionated assumptions:
+
+=over 4
+
+=item
+
+Git histories should be the non-linear histories produced by
+git-merge(1), preserving all information about divergent development
+that was later brought together.
+
+If you prefer linear histories, see dgit-maint-rebase(7).
+
+=item
+
+Maintaining convenient and powerful git workflows takes priority over
+the usefulness of the raw Debian source package.  The Debian archive
+is thought of as an output format.
+
+For example, we don't spend time curating a series of quilt patches.
+However, the information such a series would contain is readily
+available from B.
+
+=item
+
+It is more important to have the Debian package's git history be a
+descendent of upstream's git history than to use exactly the orig.tar
+that upstream makes available for download.
+
+=back
+
+=head1 GIT CONFIGURATION
+
+Add the following to your ~/.gitconfig to teach git-archive(1) how to
+compress orig tarballs:
+
+=over 4
+
+[tar "tar.xz"]
+	command = xz -c
+[tar "tar.gz"]
+	command = gzip -c
+
+=back
+
+=head1 INITIAL DEBIANISATION
+
+=head2 When upstream tags releases in git
+
+Suppose that the latest stable upstream release is 1.2.2, and this has
+been tagged '1.2.2' by upstream.
+
+=over 4
+
+% git clone -oupstream https://some.upstream/foo.git
+% cd foo
+% git verify-tag 1.2.2
+% git reset --hard 1.2.2
+% git branch --unset-upstream
+
+=back
+
+The final command detachs your master branch from the upstream remote,
+so that git doesn't try to push anything there, or merge unreleased
+upstream commits.  If you want to maintain a copy of your 

Bug#840153: Should have various tutorial manpages

[Sean Whitton]

control: tag -1 +patch

Please find attached git-am(1)-amenable patches adding some pod2man
infrastructure, and dgit-maint-merge(7).

(I'm keen to retain the authorship information in the actual manpage,
but you might not like how I've edited d/copyright, so I made that a
separate patch.)

-- 
Sean Whitton
From 45cc7d295cb818a2c236687d9d395d4712e500ce Mon Sep 17 00:00:00 2001
From: Ian Jackson 
Date: Mon, 17 Oct 2016 17:31:38 +0100
Subject: [PATCH 1/4] changelog: Finalise 2.2

Signed-off-by: Ian Jackson 
---
 debian/changelog | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/debian/changelog b/debian/changelog
index 203a864..b8811e0 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -5,7 +5,7 @@ dgit (2.2) unstable; urgency=low
   * Detect SIGPIPE (and SIGCHLD) being blocked or ignored.
 Closes:#841085.
 
- --
+ -- Ian Jackson   Mon, 17 Oct 2016 17:31:18 +0100
 
 dgit (2.1) unstable; urgency=low
 
-- 
2.9.3

From c91d5c541983977bd7f6f796ce0b39c38bd12c25 Mon Sep 17 00:00:00 2001
From: Sean Whitton 
Date: Tue, 18 Oct 2016 17:20:27 -0700
Subject: [PATCH 2/4] Makefile: build and clean *.7.pod

Signed-off-by: Sean Whitton 
---
 Makefile | 12 ++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index 6fcc9bd..3f071e3 100644
--- a/Makefile
+++ b/Makefile
@@ -33,7 +33,7 @@ txtdocdir=$(prefix)/share/doc/dgit
 
 PROGRAMS=dgit
 MAN1PAGES=dgit.1
-MAN7PAGES=dgit.7
+MAN7PAGES=dgit.7 dgit-maint-merge.7
 TXTDOCS=README.dsc-import
 PERLMODULES=Debian/Dgit.pm
 
@@ -48,7 +48,7 @@ INFRA_PERLMODULES= \
 
 all:
 
-install:	installdirs
+install:	installdirs $(MAN7PAGES)
 	$(INSTALL_PROGRAM) $(PROGRAMS) $(DESTDIR)$(bindir)
 	$(INSTALL_DATA) $(MAN1PAGES) $(DESTDIR)$(man1dir)
 	$(INSTALL_DATA) $(MAN7PAGES) $(DESTDIR)$(man7dir)
@@ -80,3 +80,11 @@ check installcheck:
 
 clean distclean mostlyclean maintainer-clean:
 	rm -rf tests/tmp
+	set -e; for m in $(MAN7PAGES); do \
+		test -e $$m.pod && rm -f $$m; \
+	done
+
+%.7: %.7.pod
+	pod2man --section=7 --date="Debian Project" --center="dgit" \
+		--name=$(subst .7,,$@) \
+		$^ $@
-- 
2.9.3

From 7d9ab53f8b47815a62a4ff4e5c19facd70c57a90 Mon Sep 17 00:00:00 2001
From: Sean Whitton 
Date: Tue, 18 Oct 2016 17:22:49 -0700
Subject: [PATCH 3/4] debian/copyright: add myself

Signed-off-by: Sean Whitton 
---
 debian/copyright | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/debian/copyright b/debian/copyright
index 493b700..88a5e6d 100644
--- a/debian/copyright
+++ b/debian/copyright
@@ -3,6 +3,8 @@ Integration between git and Debian-style archives
 
 Copyright (C)2013-2016 Ian Jackson
 
+dgit-maint-merge.7.pod is copyright (C)2016 Sean Whitton
+
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation, either version 3 of the License, or
-- 
2.9.3

From fdef83c4e1651315bda2fd86781cac136d148156 Mon Sep 17 00:00:00 2001
From: Sean Whitton 
Date: Tue, 18 Oct 2016 17:23:11 -0700
Subject: [PATCH 4/4] Manpage: add dgit-maint-merge.7.pod

Signed-off-by: Sean Whitton 
---
 dgit-maint-merge.7.pod | 365 +
 1 file changed, 365 insertions(+)
 create mode 100644 dgit-maint-merge.7.pod

diff --git a/dgit-maint-merge.7.pod b/dgit-maint-merge.7.pod
new file mode 100644
index 000..d9dcb51
--- /dev/null
+++ b/dgit-maint-merge.7.pod
@@ -0,0 +1,365 @@
+=head1 NAME
+
+dgit - tutorial for package maintainers, using a workflow centered around git-merge(1)
+
+=head1 INTRODUCTION
+
+This document describes elements of a workflow for maintaining a
+non-native Debian package using B.  The workflow makes the
+following opinionated assumptions:
+
+=over 4
+
+=item
+
+Git histories should be the non-linear histories produced by
+git-merge(1), preserving all information about divergent development
+that was later brought together.
+
+If you prefer linear histories, see dgit-maint-rebase(7).
+
+=item
+
+Maintaining convenient and powerful git workflows takes priority over
+the usefulness of the raw Debian source package.  The Debian archive
+is thought of as an output format.
+
+For example, we don't spend time curating a series of quilt patches.
+However, the information such a series would contain is readily
+available from B.
+
+=item
+
+It is more important to have the Debian package's git history be a
+descendent of upstream's git history than to use exactly the orig.tar
+that upstream makes available for download.
+
+=back
+
+=head1 GIT CONFIGURATION
+
+Add the following to your ~/.gitconfig to teach git-archive(1) how to
+compress orig tarballs:
+
+=over 4
+
+[tar "tar.xz"]
+	command = xz -c
+[tar "tar.gz"]
+	

Bug#840153: Should have various tutorial manpages

[Ian Jackson]

Sean Whitton writes ("Re: Bug#840153: Should have various tutorial manpages"):
> Would you accept a patch to your Makefile to compile manpages from
> perl's POD format?  Or is there some other format you'd prefer?  I'd
> like to confirm in advance of starting to write.

Yes.

> I'm impressed that you seem to have written the existing dgit.7 and
> dgit.1 in troff, but I'd rather not.

:-).

Ian.

-- 
Ian Jackson <ijack...@chiark.greenend.org.uk>   These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.

Bug#840153: Should have various tutorial manpages

[Sean Whitton]

Hello Ian,

Would you accept a patch to your Makefile to compile manpages from
perl's POD format?  Or is there some other format you'd prefer?  I'd
like to confirm in advance of starting to write.

I'm impressed that you seem to have written the existing dgit.7 and
dgit.1 in troff, but I'd rather not.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#840153: Should have various tutorial manpages

[Ian Jackson]

Package: dgit
Version: 1.4

For example:

 dgit-userfor users of any Debian-derived distro,
including how to edit packages

 dgit-nmu-simple  for Debian developers doing an NMU

 dgit-maint-nativemaintain native packages in Debian

 dgit-maint-merge maintain packages in Debian, using git merge

 dgit-maint-rebasemaintain packages in Debian, using git rebase

 dgit-maint-gbp   maintain packages in Debian, using git-buildpackage

 dgit-maint-dpm   maintain packages in Debian, using git-dpm

 dgit-downstream-dsc  how to set up a downstream distro which
publishes source packages


-- 
Ian Jackson    These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.