Re: [PATCH] docs: include "trace.h" in MyFirstObjectWalk.txt

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 30, 2023, 16:25 UTC
Message-ID: <xmqqsfa87w9o.fsf@gitster.g>
In-Reply-To: <CADE8NapyQJU1rDPvyMcRXcJfz3kzzg_fYXSSEvYJ7dFO+UHGaQ@mail.gmail.com>

Vinayak Dev <vinayakdev.sci@gmail.com> writes:

> That is a good suggestion, but wouldn't the same argument apply to
> including trace.h itself? It makes it necessary for the code to work
> that any API changes must involve changing the included headers.

Exactly. That is exactly what I meant by "tone down 'defined in X' somehow to hint that these details may change".

IOW, it may allow us to "cop out" of the problem to say "You'd add a new file like so, and call this API function, and include headers necessary to do so. The codebase may have evolved since this tutorial was written, so some details (like names of the API functions and in which header files the functions are declared) may be different in the code you have."

> Either way, I would be happy to fix my mistake. Should I send out a V2?

Oh, sorry to see you took it that way. I think the change you sent as-is is a fine fix for the immediate problem. Everything you quoted above is "while the issue is fresh on our minds, what are the follow-up improvements we can make" material, so there is no "mistake" to fix.