bug#20637: incompatible, undocumented change to vc-working-revision

[Michael Albinus <michael.albinus@gmx.de>]

Dmitry Gutov <dgutov@yandex.ru> writes:

> On 04/14/2016 09:31 PM, Michael Albinus wrote:
>
>> Yes. I hope we could use more file properties caches. To be investigated.
>
> OK, that could be a fine solution to the problem of vc-registered's
> slowness, but it adds complexity. So I'm still in favor of equating
> `unregistered' with nil, .

I'm not against this. But I would like to see the whole picture
first. Where else unregistered is used, and whether we run into
conflicts when using nil instead of unregistered.

>> And as said already several times, if
>> we would document vc-* functions in the manual, it would allow us to
>> have a more global view on proposed changes.
>
> I disagree. The manual is the documentation for the users, to explain
> in depth, give examples, et cetera. The docstrings and VC's internal
> documentation have to stand on their own. It would be silly if the
> difference between `vc-backend' and `vc-responsible-backend' were to
> only be explained in the manual, but not in the docstrings.

Are we speaking about different manuals? I'm speaking about the ‘GNU
Emacs Lisp Reference Manual’, and not the ‘GNU Emacs Manual’ (the manual
dedicated to users).

> That would also be unfair to people such as myself who prefer to
> consult the latter.

With your argument, we could nuke the Emacs Lisp manual. Shall we?

> So, do you need anything from me in this area? E.g., feel free to give
> a list of docstrings that seem insufficient to you, together with what
> you feel they are missing.

I will start somehow, and show you for review.

>> I trust you that you have all involved interfaces in your mind. I
>> haven't, and I would like to see how an interface change compares to
>> the other interfaces.
>
> I don't really know everything about VC, I just have some
> recollections about dealing with it, as well as experience writing a
> third-party package depending on VC's API.
>
> To get an opinion about the current bug report, I still had to dig
> into the code and investigate, look at the commit history, search for
> call occurrences, etc.

My first sentence above is a rhetorical one, of course :-)

>> But you have spoken about
>> design decisions in the past (for example whether unregistered files
>> could be an argument), which I believe is not documented.
>
> BTW, we've mentioned it before when fixing my old bug report about VC
> using too many process calls
> (http://debbugs.gnu.org/cgi/bugreport.cgi?bug=11757#77).

Yes, but that's not the documentation! I'm pretty good in forgetting
everything, and I don't remember what was said in message 77 of bug
report 11757, months ago ...

> It may not have even been a deliberate design decision, but it's the
> way `vc-state' is used. Which, in turn, allows backend implementations
> to be sloppy in the cases that are (almost?) never exercised.
>
>> And at least for me the "global view" about vc-* functions is missing,
>> and how they are related.
>
> I usually tease that kind of information out by reading the source
> code. Is there anything in particular I could help add to your
> understanding of the "global view"?

Even if I understand it, it won't help any other developer. Let's
document it.

>> Yep. Pls test my patch, and confirm whether it is sufficient. Same for
>> Glenn, if possible. I would like to close this bug then, removing a
>> release blocker for Emacs 25.1.
>
> It must fix this bug, since it reverts to the old code, and testing
> Glenn's example from the description confirms as much.
>
> So I think it can be closed, and the discussion should move to emacs-devel.

OK, I'm waiting for some few days (maybe Glenn want to say something
about), and then I'll close this bug. Thanks for all your help this way!

Best regards, Michael.