On Mon, Mar 25, 2024 at 10:50 AM Junio C Hamano <gitster@xxxxxxxxx> wrote: > > Dirk Gouders <dirk@xxxxxxxxxxx> 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. >
