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

From: Vinayak Dev <vinayakdev.sci@gmail.com>
Date: Jun 30, 2023, 06:09 UTC
Message-ID: <CADE8NapyQJU1rDPvyMcRXcJfz3kzzg_fYXSSEvYJ7dFO+UHGaQ@mail.gmail.com>
In-Reply-To: <xmqqjzvm7z13.fsf@gitster.g>

On Fri, 30 Jun 2023 at 02:43, Junio C Hamano <gitster@pobox.com> wrote:

Hi, thanks for replying!

Show 10 quoted lines

> All of the above may be good currently, but as soon as somebody does
> another round of header shuffling, we risk a very similar breakage.
> It is a good time to think about ways to avoid that, while the pain
> is fresh in our mind.
>
> One "cop out" thing we can do to limit the damage may be to loosen
> the text in the "NOTE:", so that it does *NOT* mention exact header
> files the API functions appear and let the readers learn from the
> source themselves, with "git grep" helping their way.  Or tone down
> "defined in X" somehow to hint that these details may change.

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. Either way, I would be happy to fix my mistake. Should I send out a V2?

Show 8 quoted lines

> More effective things that would involve higher implementation cost
> (but will reduce maintenance cost) would be to actually make sure
> that those who update the API will notice that they are breaking
> these samples when they develop their series.
>
> In https://lore.kernel.org/git/xmqq1qhu9ifp.fsf@gitster.g/, I've
> floated some strawman ideas but people may be able to invent better
> ways.

I do want to be a part of the discussion and the solution, so if I am able to find a reasonable way(or to implement a solution), I would inform everyone for sure.

Thanks a lot! Vinayak