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.
