Re: [PATCH v3 0/5] Fixes for Documentation/MyFirstObjectWalk.txt

From: Kyle Lippincott <spectral@google.com>
To: Junio C Hamano <gitster@pobox.com>
Cc: Dirk Gouders <dirk@gouders.net>,
	git@vger.kernel.org,  Emily Shaffer <emilyshaffer@google.com>
Subject: Re: [PATCH v3 0/5] Fixes for Documentation/MyFirstObjectWalk.txt
Date: Mon, 25 Mar 2024 11:01:07 -0700	[thread overview]
Message-ID: <CAO_smVh9TBiJivDrB6wFhAS6adKRqFiu7FE=H5ui5yQ5ssiuqA@mail.gmail.com> (raw)
In-Reply-To: <xmqqsf0ekxpu.fsf@gitster.g>

On Mon, Mar 25, 2024 at 10:50 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> Dirk Gouders <dirk@gouders.net> writes:
>
> > The 3rd iteration for this series.
> >
> > I tried to credit Kyle's suggestions for 4 and 5 with Helped-by tags and
> > hope it was adequate to do so.  Actually, at least #4 was a lot more
> > than a Helped-by, I would say...
>
> It seemed adequate, at least to me, but I'll leave the final say up
> to Kyle.
>
> I left a few comments but overall the series is looking much nicer.
> Thanks for working on it (and thanks for reviewing and helping,
> Kyle).
>
> This is an unrelated tangent, but I wonder if we can come up with a
> way to find breakages coming from API updates to these "tutorial"
> documents.  The original "user-manual" also shares the same issue,
> and the issue may be deeper there as it also needs to catch up with
> end-user facing UI updates.  In any case, we somehow ended up with
> two more "tutorial"-ish documents (MyFirstContribution.txt is the
> other one) that somebody needs to keep an eye on.
>
> Ideally if we can have automated tests, it would be nice.  Perhaps
> sprinkling some special instruction in comments that is hidden from
> AsciiDoc mark-up to help our custom program to assemble the bits
> into the state of the tutorial program that the readers should be
> arriving at at different points in the tutorial document, and make
> sure they compile, link, and test well?

On another project, I've had a (separate) test file that just does
what the tutorial says to do, and there's an automatic notice for
"you're touching tutorial-test.sh, make sure you make any required
changes to tutorial.txt as well". I don't know if we have that second
part available to us here, though.

> Or "follow one of our three
> tutorial documents to the letter to see if they need adjusting, and
> come up with a set of patches to adjust them" can be listed as one
> of the microproject ideas?  I'll leave a #leftoverbits mark here, but
> what I want to see discussed (and eventually implemented) is not the
> clean-up itself (which can go stale over time) but the strategy to
> keep the "tutorial" material up-to-date.
>
> THanks.
>