Documentation/MyFirstObjectWalk: add #include "trace.h" to use trace_printf()

>
> Hey there!
> I was looking through Documentation/MyFirstObjectWalk.txt, and upon
> building the branch containing the given code, I find that I get the
> error that C99 does not allow implicit function declaration where
> trace_printf() is encountered. However, upon including trace.h the
> error disappears, and the build proceeds just fine.
>
> I did put DEVELOPER=1 in config.mak before building, but it doesn't
> seem to work.
>
> Is the error pointing to a problem, or am I doing something wrong?
> If it is the former, I would be very happy to send a patch fixing this.

>
> On Thu, Jun 29, 2023 at 9:06 AM Vinayak Dev <vinayakdev.sci@gmail.com> wrote:
> >
> > Hey there!
> > I was looking through Documentation/MyFirstObjectWalk.txt, and upon
> > building the branch containing the given code, I find that I get the
> > error that C99 does not allow implicit function declaration where
> > trace_printf() is encountered. However, upon including trace.h the
> > error disappears, and the build proceeds just fine.
> >
> > I did put DEVELOPER=1 in config.mak before building, but it doesn't
> > seem to work.
> >
> > Is the error pointing to a problem, or am I doing something wrong?
> > If it is the former, I would be very happy to send a patch fixing this.
>
> Yeah, it's almost certainly stale in MyFirstObjectWalk - there was
> very recently a patch to clean up some headers which probably were
> implicitly including trace.h when I wrote this walkthrough. Patches
> totally welcome - and if you were working from the reference code in
> https://github.com/nasamuffin/git/tree/myfirstrevwalk

> and it's on your
> way to rebase and fix that too, I'm happy to update my branch
> accordingly too. (If you weren't, don't worry about doing the extra
> work, though.)
>
> >
> > Thanks a lot!
> > Vinayak

> > Yeah, it's almost certainly stale in MyFirstObjectWalk - there was
> > very recently a patch to clean up some headers which probably were
> > implicitly including trace.h when I wrote this walkthrough. Patches
> > totally welcome - and if you were working from the reference code in
> > https://github.com/nasamuffin/git/tree/myfirstrevwalk
>
> bah, wrong link, the tutorial points to branch `revwalk` instead of
> `myfirstrevwalk`, but the offer stands :)
>
> > and it's on your
> > way to rebase and fix that too, I'm happy to update my branch
> > accordingly too. (If you weren't, don't worry about doing the extra
> > work, though.)

>
> > On Thu, Jun 29, 2023 at 9:33 AM Emily Shaffer <nasamuffin@google.com> wrote:
>
> Hi, thanks for replying!
>
> > > Yeah, it's almost certainly stale in MyFirstObjectWalk - there was
> > > very recently a patch to clean up some headers which probably were
> > > implicitly including trace.h when I wrote this walkthrough. Patches
> > > totally welcome - and if you were working from the reference code in
> > > https://github.com/nasamuffin/git/tree/myfirstrevwalk
> >
> > bah, wrong link, the tutorial points to branch `revwalk` instead of
> > `myfirstrevwalk`, but the offer stands :)
> >
> > > and it's on your
> > > way to rebase and fix that too, I'm happy to update my branch
> > > accordingly too. (If you weren't, don't worry about doing the extra
> > > work, though.)
>
> Sure will! But do you mean open a PR on your fork? I have the patch ready,
> and would be very happy to do so, if it is accepted!

> Yeah, I think there are two things to fix:
>
> First, a patch to Documentation/technical/MyFirstObjectWalk.txt fixing
> the snippets there. (I thought that was what you were offering to
> patch in your original mail, I may have been mistaken.)
>
> Second, optionally, a rebased-and-fixed-and-your-attribution-added
> branch of the reference impl that I can force-push to nasamuffin/git.
> The more I think on it, I don't think the PR will help, since I will
> want to just force-push that whole branch so the commit order still
> functions as a learning tool. So if you have it even in a branch on
> your GitHub or GitLab fork, or a series of patches you'd want to mail
> to me, any of those are fine and I'll go ahead and rewrite my branch.

>
> Emily Shaffer <nasamuffin@google.com> writes:
>
> > Yeah, it's almost certainly stale in MyFirstObjectWalk - there was
> > very recently a patch to clean up some headers which probably were
> > implicitly including trace.h when I wrote this walkthrough.
>
> We are lucky that we have folks like Vinayak who tried out the
> examples and then bothered to spend time reporting the failure
> discovered.  What does it take, however, for us to have a bit more
> automated way to prevent such a breakage that comes from API
> changes?  Is it feasible, for example, to add a test that extracts
> code snippets from the MyFirstObjectWalk document and try to build
> the result?  Alternatively, we can ship such a set of sample source
> files somewhere in our tree (e.g. contrib/examples?) and have such
> a test try to build using the current set of source files, but then
> we need a mechansim to ensure that the sample source files will not
> go out of sync with the document.

>
> Thoughts?
>
> Thanks.
>

> ... I do very much
> like the idea of keeping the reference source in contrib/ as a set of
> patches, maybe along with a script to apply them (or a readme with the
> right `git am` invocation), and then checking that they still build.
> Checking that against the contents of the document is trickier,
> though, like you mentioned. Hm.