Hi, Sorry for the delay, $work got too busy.
On Wed, Feb 21, 2018 at 8:45 PM, Ian Jackson <[email protected]> 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 a normal git push.) Right. The aliases would make it clearer for non-experts when you actually want to lose data. If I have no idea how dgit works, but there is an option --first-dgit-push, I'll probably use it when pushing a package for the first time. OTOH, I'm a lot less likely to use an option that is named 'overwrite' :) -- Saludos, Felipe Sateler
