Re: [PATCH] documentation: add tutorial for revision walking

[Emily Shaffer <emilyshaffer@google.com>]

On Mon, Jun 10, 2019 at 01:25:14PM -0700, Junio C Hamano wrote:
> Emily Shaffer <emilyshaffer@google.com> writes:
> 
> > I'll also be mailing an RFC patchset In-Reply-To this message; the RFC
> > patchset should not be merged to Git, as I intend to host it in my own
> > mirror as an example. I hosted a similar example for the
> > MyFirstContribution tutorial; it's visible at
> > https://github.com/nasamuffin/git/tree/psuh. There might be a better
> > place to host these so I don't "own" them but I'm not sure what it is;
> > keeping them as a live branch somewhere struck me as an okay way to keep
> > them from getting stale.
> 
> Yes, writing the initial version is one thing, but keeping it alive
> is more work and more important.  As the underlying API changes over
> time, it will become necessary to update the sample implementation,
> but for a newbie who wants to learn by building "walken" on top of
> the then-current codebase and API, it would not be so helpful to
> show "these 7 patches were for older codebase, and the tip 2 are
> incremental updates to adjust to the newer API", so the maintenance
> of these sample patches may need different paradigm than the norm
> for our main codebase that values incremental polishing.
>
I'm trying to think of how it would end up working if I tried to use a
Github workflow. I think it wouldn't - someone would open a PR, and then
I'd have to rewrite that change into the appropriate commit in the live
branch and push the entire branch anew. Considering that workflow leaves
me doubly convinced that leaving it in my personal fork indefinitely
might not be wise (what if I become unable to continue maintaining it)?

I wonder if this is something that might fit well in
one of the more closely-associated mirrors, like gitster/git or
gitgitgadget/git - although I wonder if those count as "owned" by Junio
and Johannes, respectively. Hmmmm.

Maybe there's a case for storing them as a set of patch files that are
revision-controlled somewhere within Documentation/? There was some
discussion on the IRC a few weeks ago about trying to organize these
tutorials into their own directory to form a sort of "Git Contribution
101" course, maybe it makes sense to store there?

  Documentation/contributing/myfirstcontrib/MyFirstContrib.txt
  Documentation/contributing/myfirstcontrib/sample/*.patch
  Documentation/contributing/myfirstrevwalk/MyFirstRevWalk.txt
  Documentation/contributing/myfirstrevwalk/sample/*.patch

I don't love the idea of maintaining text patches with the expectation
that they should cleanly apply always, but it might make the idea that
they shouldn't contain 2 patches on the tip for API adjustment more
clear. And it would be probably pretty easy to inflate and build them
with a build target or something. Hmmmmmmmmm.

 - Emily