| Message ID | cover.1711368498.git.dirk@gouders.net (mailing list archive) |
|---|---|
| Headers | show |
| Series | Fixes for Documentation/MyFirstObjectWalk.txt | expand |
On Mon, Mar 25, 2024 at 6:19 AM Dirk Gouders <dirk@gouders.net> wrote: > > 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... > --- > Changes in v3: > * Reword the description in [4/5] > * Add a missing slash in [5/5] > > Changes in v2: > * Added Emily to Cc in the hope for a review > * Remove superfluous tags from [1/5] and [3/5] > * Replace bashism `|&` by `2>&1 |` in [5/5] > --- > Dirk Gouders (5): > MyFirstObjectWalk: use additional arg in config_fn_t > MyFirstObjectWalk: fix misspelled "builtins/" > MyFirstObjectWalk: fix filtered object walk > MyFirstObjectWalk: fix description for counting omitted objects > MyFirstObjectWalk: add stderr to pipe processing > > Documentation/MyFirstObjectWalk.txt | 36 ++++++++++++++++------------- > 1 file changed, 20 insertions(+), 16 deletions(-) > > Range-diff against v2: > -: ---------- > 1: 0eeb4b78ac MyFirstObjectWalk: use additional arg in config_fn_t > -: ---------- > 2: 3122ae2472 MyFirstObjectWalk: fix misspelled "builtins/" > -: ---------- > 3: f21348ab80 MyFirstObjectWalk: fix filtered object walk Looks good, thanks again!
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? 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.
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. >
Kyle Lippincott <spectral@google.com> writes: > On Mon, Mar 25, 2024 at 6:19 AM Dirk Gouders <dirk@gouders.net> wrote: >> >> 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... >> --- >> Changes in v3: >> * Reword the description in [4/5] >> * Add a missing slash in [5/5] >> >> Changes in v2: >> * Added Emily to Cc in the hope for a review >> * Remove superfluous tags from [1/5] and [3/5] >> * Replace bashism `|&` by `2>&1 |` in [5/5] >> --- >> Dirk Gouders (5): >> MyFirstObjectWalk: use additional arg in config_fn_t >> MyFirstObjectWalk: fix misspelled "builtins/" >> MyFirstObjectWalk: fix filtered object walk >> MyFirstObjectWalk: fix description for counting omitted objects >> MyFirstObjectWalk: add stderr to pipe processing >> >> Documentation/MyFirstObjectWalk.txt | 36 ++++++++++++++++------------- >> 1 file changed, 20 insertions(+), 16 deletions(-) >> >> Range-diff against v2: >> -: ---------- > 1: 0eeb4b78ac MyFirstObjectWalk: use additional arg in config_fn_t >> -: ---------- > 2: 3122ae2472 MyFirstObjectWalk: fix misspelled "builtins/" >> -: ---------- > 3: f21348ab80 MyFirstObjectWalk: fix filtered object walk > > Looks good, thanks again! Thank you for looking at it. Dirk
Junio C Hamano <gitster@pobox.com> writes: > 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. My plan was to also work through MyFirstContribution.txt and test everything which at least should disclose currently existing issues. But, besides those tutorial documents, many manual pages also contain examples and I wonder how these are maintained. Dirk
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... --- Changes in v3: * Reword the description in [4/5] * Add a missing slash in [5/5] Changes in v2: * Added Emily to Cc in the hope for a review * Remove superfluous tags from [1/5] and [3/5] * Replace bashism `|&` by `2>&1 |` in [5/5] --- Dirk Gouders (5): MyFirstObjectWalk: use additional arg in config_fn_t MyFirstObjectWalk: fix misspelled "builtins/" MyFirstObjectWalk: fix filtered object walk MyFirstObjectWalk: fix description for counting omitted objects MyFirstObjectWalk: add stderr to pipe processing Documentation/MyFirstObjectWalk.txt | 36 ++++++++++++++++------------- 1 file changed, 20 insertions(+), 16 deletions(-) Range-diff against v2: -: ---------- > 1: 0eeb4b78ac MyFirstObjectWalk: use additional arg in config_fn_t -: ---------- > 2: 3122ae2472 MyFirstObjectWalk: fix misspelled "builtins/" -: ---------- > 3: f21348ab80 MyFirstObjectWalk: fix filtered object walk 1: 4219237868 ! 4: cfa4b9ce50 MyFirstObjectWalk: fix description for counting omitted objects @@ Commit message Fix the text to clarify that we now use another traversal function to be able to pass the pointer to the introduced oidset. + Helped-by: Kyle Lippincott <spectral@google.com> Signed-off-by: Dirk Gouders <dirk@gouders.net> ## Documentation/MyFirstObjectWalk.txt ## @@ Documentation/MyFirstObjectWalk.txt: points to the same tree object as its grand -`traverse_commit_list_filtered()` to populate the `omitted` list means that our -object walk does not perform any better than an unfiltered object walk; all -reachable objects are walked in order to populate the list. -+filter, like with `git log --filter=<spec> --filter-print-omitted`. We -+can ask `traverse_commit_list_filtered()` to populate the `omitted` -+list which means that our object walk does not perform any better than -+an unfiltered object walk; all reachable objects are walked in order -+to populate the list. ++filter, like with `git log --filter=<spec> --filter-print-omitted`. To do this, ++change `traverse_commit_list()` to `traverse_commit_list_filtered()`, which is ++able to populate an `omitted` list. Note that this means that our object walk ++will not perform any better than an unfiltered object walk; all reachable ++objects are walked in order to populate the list. First, add the `struct oidset` and related items we will use to iterate it: @@ Documentation/MyFirstObjectWalk.txt: static void walken_object_walk( -Modify the call to `traverse_commit_list_filtered()` to include your `omitted` -object: -+You need to replace the call to `traverse_commit_list()` to -+`traverse_commit_list_filtered()` to be able to pass a pointer to the -+oidset defined and initialized above: ++Replace the call to `traverse_commit_list()` with ++`traverse_commit_list_filtered()` and pass a pointer to the `omitted` oidset ++defined and initialized above: ---- ... 2: 9b0f0832b7 ! 5: c571abb49d MyFirstObjectWalk: add stderr to pipe processing @@ Commit message Fix this by redirecting stderr to stdout prior to the pipe operator to additionally connect stderr to stdin of the latter command. + Further, while reviewing the above fix, Kyle Lippincott noticed + a second issue with the second of the examples: a missing slash in the + executable path "./bin-wrappers git". + + Add the missing slash. + + Helped-by: Kyle Lippincott <spectral@google.com> Signed-off-by: Dirk Gouders <dirk@gouders.net> ## Documentation/MyFirstObjectWalk.txt ## @@ Documentation/MyFirstObjectWalk.txt: of the first handful: ---- $ make -$ GIT_TRACE=1 ./bin-wrappers git walken | tail -n 10 -+$ GIT_TRACE=1 ./bin-wrappers git walken 2>&1 | tail -n 10 ++$ GIT_TRACE=1 ./bin-wrappers/git walken 2>&1 | tail -n 10 ---- The last commit object given should have the same OID as the one we saw at the