Bug#891031: dgit: Please make the unavoidable error message on first push more user-friendly

[Ian Jackson]

I'm changing the messages so it looks like this:

  [lots of blather]
  Checking that HEAD inciudes all changes in archive...
  dgit: error: Wanted tag maintainer view tag (test-dummy/1.0-1) on dgit 
server, but not found
  | Not fast forward; maybe --overwrite is needed, see dgit(1)
  ! Push failed, while preparing your push.
  ! You can retry the push, after fixing the problem, if you like.
  $

And I have added a note to dgit(1) saying:

  This  option  is also usually necessary the first time a package
  is pushed with dgit push to a particular suite.  See dgit-
  maint-*(7).

Ian.

-- 
Ian JacksonThese 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#891031: dgit: Please make the unavoidable error message on first push more user-friendly

[Felipe Sateler]

On Sat, Feb 24, 2018 at 3:06 PM, Sean Whitton  wrote:
> Hello Ian and Felipe,
>
> On Wed, Feb 21 2018, Ian Jackson wrote:
>
>> Hi.  Thanks for your feedback.  I'm always interested in making things
>> smoother.
>
> Ditto.
>
>> The reason I'm asking all of these questions about which docs you read
>> is not to tell you to RTFM.  It's that I would like to understand how
>> and where best to communicate this information.  There's more room in
>> the manual than in an error message.
>
> I suggest that this kind of issue could be resolved if the final output
> of the failed command, which is prefixed with '!', included hints such
> as the one that says "consult --overwrite documentation".  As it stands
> such hints appear above this final section.
>
> dgit produces a lot of output, but there already exists a clearly
> designated "error summary" section.  The most important hints should be
> moved into that section.
>
> Lines like "dgit: Wanted tag maintainer view tag (debian/0.11-5) on dgit
> server, but not found" are much less important and can remain in the
> general output.

This is a very good suggestion indeed. Putting the error message in a
dedicated block at the end should help a lot.

-- 

Saludos,
Felipe Sateler

Bug#891031: dgit: Please make the unavoidable error message on first push more user-friendly

[Felipe Sateler]

Hi,

Sorry for the delay, $work got too busy.

On Wed, Feb 21, 2018 at 8:45 PM, Ian Jackson
<ijack...@chiark.greenend.org.uk> wrote:
> Felipe Sateler writes ("Bug#891031: dgit: Please make the unavoidable error 
> message on first push more user-friendly"):
>> Prodded by Sean Whitton's blog post[1], I decided to give dgit another
>> try. I found an upload I needed to do, and used `dgit push-source
>> --gbp`, only to have that fail with the following tail:
>
> Hi.  Thanks for your feedback.  I'm always interested in making things
> smoother.
>
>> > Checking that HEAD inciudes all changes in archive...
>> > dgit: check failed (maybe --overwrite is needed, consult documentation)
> ...
>> I suppose this gives an experienced user all the information they need,
>> but for a newcomer this is unparseable. The problem is fixed by passing
>> --overwrite (as correctly suggested), but the phrasing could be
>> improved. An option named --overwrite sounds fairly advanced, when in
>> fact it isn't. Some thoughts:
>
> JOOI, did you consult the documentation as advised ?  The intent of
> that message was that you would read dgit(1), really - particularly,
> that you would read the description of --overwrite.  Is that what you
> understood the message was referring you to ?  If not, what did you
> read instead ?

Yes, I did read dgit(1), but that wasn't immediately enlightening.

>
> Unfortunately dgit(1) does not mention this situation (or at least,
> not in any readily comprehensible way) so reading it wouldn't have
> helped you, but it seems to be where it probably ought to be.

The description of --overwrite seems to me to assume a lot of
knowledge about how dgit works. Perhaps that is why I did not manage
to answer the question "maybe --overwrite is needed".

>
> I guess you didn't read dgit-maint-gbp(7) ?  That does discuss this,
> but I don't think people should be expected to go and read tutorial
> docs in response to error messages.

I had read that manual a while ago on my first interactions with dgit,
but I had not re-read it this time.

>
> The reason I'm asking all of these questions about which docs you read
> is not to tell you to RTFM.  It's that I would like to understand how
> and where best to communicate this information.  There's more room in
> the manual than in an error message.
>
> In particular --overwrite *is* an option which should be used with
> care.  It's a forcing option which can indeed unintentionally drop
> other people's work.  I don't think it's possible to put all the
> appropriate caveats in the message; so it is always going to be
> necessary for the user who needs --ovewrite to be referred to the
> docs, rather than be actively encouraged to use a moderately dangerous
> option.

I think my problem here is that, because I don't understand completely
how dgit works, I couldn't work out that:

1. This problem is expected
2. The way to fix my problem is to: "make a pseudo-merge to stitch the
archive's version into your own git history".

I think the small blurb from the dgit-maint-gbp manual could be moved
to --overwrite, so that the manual not only describes what the option
does, but also why such a possibly lossy option is needed.

If the option documentation gets too long, perhaps a new section in
dgit(1), titled "Resolving non-fast-forward pushes" could be written
and have --overwrite point there.

>
>> 1. Adding a short blurb indicating common causes of this specific error.
>>AFAICT, the most common causes are: first use of dgit, and
>>incorporating NMUs without dgit use. Something like "This usually
>>happens when the last upload was not done using dgit" would go a long
>>way towards demistifying the new user.
>
> The "NMU" case is discussed in dgit(1)'s section on --overwrite.
>
>> 2. It occurs to me this situation can be avoided entirely for some cases
>>if dgit can detect the dgit history is composed entirely of
>>synthesized commits (ie, imports from the debian archive and not dgit
>>pushes), or is empty. I have no idea if this is feasible though.
>
> I think this is feasible, at least in "many cases", and probably
> worthwhile.  I think it is usually better to get rid of a wrinkle than
> to document it.

This would be the best solution, but just enhancing the documentation
could be sufficient.

>
>> 3. As said, --overwrite sounds potentially data-lossy, but is the only
>>solution to this predicament. Maybe it is desirable to have aliases
>>for the common cases: --first-dgit-push or some such.
>
> --overwrite *is* potentially data-lossy.  (Like any upload to the
> Debian archive, but unlike

Bug#891031: dgit: Please make the unavoidable error message on first push more user-friendly

[Sean Whitton]

Hello Ian and Felipe,

On Wed, Feb 21 2018, Ian Jackson wrote:

> Hi.  Thanks for your feedback.  I'm always interested in making things
> smoother.

Ditto.

> The reason I'm asking all of these questions about which docs you read
> is not to tell you to RTFM.  It's that I would like to understand how
> and where best to communicate this information.  There's more room in
> the manual than in an error message.

I suggest that this kind of issue could be resolved if the final output
of the failed command, which is prefixed with '!', included hints such
as the one that says "consult --overwrite documentation".  As it stands
such hints appear above this final section.

dgit produces a lot of output, but there already exists a clearly
designated "error summary" section.  The most important hints should be
moved into that section.

Lines like "dgit: Wanted tag maintainer view tag (debian/0.11-5) on dgit
server, but not found" are much less important and can remain in the
general output.

>> [1] https://spwhitton.name//blog/entry/pushsourcedropin/
>
> I observe that Sean's blog post does mention the --overwrite wrinkle,
> althought it doesn't say in terms that it will always be needed on the
> first upload.

Fixed, thanks.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#891031: dgit: Please make the unavoidable error message on first push more user-friendly

[Ian Jackson]

Felipe Sateler writes ("Bug#891031: dgit: Please make the unavoidable error 
message on first push more user-friendly"):
> Prodded by Sean Whitton's blog post[1], I decided to give dgit another
> try. I found an upload I needed to do, and used `dgit push-source
> --gbp`, only to have that fail with the following tail:

Hi.  Thanks for your feedback.  I'm always interested in making things
smoother.

> > Checking that HEAD inciudes all changes in archive...
> > dgit: check failed (maybe --overwrite is needed, consult documentation)
...
> I suppose this gives an experienced user all the information they need,
> but for a newcomer this is unparseable. The problem is fixed by passing
> --overwrite (as correctly suggested), but the phrasing could be
> improved. An option named --overwrite sounds fairly advanced, when in
> fact it isn't. Some thoughts:

JOOI, did you consult the documentation as advised ?  The intent of
that message was that you would read dgit(1), really - particularly,
that you would read the description of --overwrite.  Is that what you
understood the message was referring you to ?  If not, what did you
read instead ?

Unfortunately dgit(1) does not mention this situation (or at least,
not in any readily comprehensible way) so reading it wouldn't have
helped you, but it seems to be where it probably ought to be.

I guess you didn't read dgit-maint-gbp(7) ?  That does discuss this,
but I don't think people should be expected to go and read tutorial
docs in response to error messages.

The reason I'm asking all of these questions about which docs you read
is not to tell you to RTFM.  It's that I would like to understand how
and where best to communicate this information.  There's more room in
the manual than in an error message.

In particular --overwrite *is* an option which should be used with
care.  It's a forcing option which can indeed unintentionally drop
other people's work.  I don't think it's possible to put all the
appropriate caveats in the message; so it is always going to be
necessary for the user who needs --ovewrite to be referred to the
docs, rather than be actively encouraged to use a moderately dangerous
option.

> 1. Adding a short blurb indicating common causes of this specific error.
>AFAICT, the most common causes are: first use of dgit, and
>incorporating NMUs without dgit use. Something like "This usually 
>happens when the last upload was not done using dgit" would go a long
>way towards demistifying the new user.

The "NMU" case is discussed in dgit(1)'s section on --overwrite.

> 2. It occurs to me this situation can be avoided entirely for some cases
>if dgit can detect the dgit history is composed entirely of
>synthesized commits (ie, imports from the debian archive and not dgit
>pushes), or is empty. I have no idea if this is feasible though.

I think this is feasible, at least in "many cases", and probably
worthwhile.  I think it is usually better to get rid of a wrinkle than
to document it.

> 3. As said, --overwrite sounds potentially data-lossy, but is the only
>solution to this predicament. Maybe it is desirable to have aliases
>for the common cases: --first-dgit-push or some such.

--overwrite *is* potentially data-lossy.  (Like any upload to the
Debian archive, but unlike a normal git push.)

> [1] https://spwhitton.name//blog/entry/pushsourcedropin/

I observe that Sean's blog post does mention the --overwrite wrinkle,
althought it doesn't say in terms that it will always be needed on the
first upload.

Regards,
Ian.

Bug#891031: dgit: Please make the unavoidable error message on first push more user-friendly

[Felipe Sateler]

Package: dgit
Version: 4.3
Severity: minor
Tags: upstream

Hi,

Prodded by Sean Whitton's blog post[1], I decided to give dgit another
try. I found an upload I needed to do, and used `dgit push-source
--gbp`, only to have that fail with the following tail:

> synthesised git commit from .dsc 0.11-5
> dgit: split brain (separate dgit view) may be needed (--quilt=gbp).
> dgit view: found cached (commit id a83cdaf57fc92b42d16a912aeedc1633971604c2)
> Checking that HEAD inciudes all changes in archive...
> dgit: check failed (maybe --overwrite is needed, consult documentation)
> dgit: Wanted tag maintainer view tag (debian/0.11-5) on dgit server, but not 
> found
> ! Push failed, while preparing your push.
> ! You can retry the push, after fixing the problem, if you like.

I suppose this gives an experienced user all the information they need,
but for a newcomer this is unparseable. The problem is fixed by passing
--overwrite (as correctly suggested), but the phrasing could be
improved. An option named --overwrite sounds fairly advanced, when in
fact it isn't. Some thoughts:

1. Adding a short blurb indicating common causes of this specific error.
   AFAICT, the most common causes are: first use of dgit, and
   incorporating NMUs without dgit use. Something like "This usually 
   happens when the last upload was not done using dgit" would go a long
   way towards demistifying the new user.
2. It occurs to me this situation can be avoided entirely for some cases
   if dgit can detect the dgit history is composed entirely of
   synthesized commits (ie, imports from the debian archive and not dgit
   pushes), or is empty. I have no idea if this is feasible though.
3. As said, --overwrite sounds potentially data-lossy, but is the only
   solution to this predicament. Maybe it is desirable to have aliases
   for the common cases: --first-dgit-push or some such.



[1] https://spwhitton.name//blog/entry/pushsourcedropin/

-- System Information:
Debian Release: buster/sid
  APT prefers unstable-debug
  APT policy: (500, 'unstable-debug'), (500, 'unstable'), (1, 
'experimental-debug'), (1, 'experimental')
Architecture: amd64 (x86_64)

Kernel: Linux 4.14.0-3-amd64 (SMP w/4 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), 
LANGUAGE=en_US:en (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled

Versions of packages dgit depends on:
ii  apt   1.6~alpha7
ii  ca-certificates   20170717
ii  coreutils 8.28-1
ii  curl  7.58.0-2
ii  devscripts2.17.12
ii  dpkg-dev  1.19.0.5
ii  dput  1.0.1
ii  git [git-core]1:2.16.1-1
ii  git-buildpackage  0.9.7
ii  libdpkg-perl  1.19.0.5
ii  libjson-perl  2.97001-1
ii  liblist-moreutils-perl0.416-1+b3
ii  libperl5.26 [libdigest-sha-perl]  5.26.1-4+b1
ii  libtext-glob-perl 0.10-1
ii  libtext-iconv-perl1.7-5+b6
ii  libwww-perl   6.31-1
ii  perl  5.26.1-4+b1

Versions of packages dgit recommends:
ii  openssh-client [ssh-client]  1:7.6p1-4

Versions of packages dgit suggests:
ii  sbuild  0.73.0-4

-- no debconf information