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

From: Emily Shaffer <emilyshaffer@google.com>
Date: Jun 17, 2019, 23:50 UTC
Message-ID: <20190617235053.GD100487@google.com>
In-Reply-To: <xmqqef41mbmd.fsf@gitster-ct.c.googlers.com>

On Mon, Jun 10, 2019 at 01:25:14PM -0700, Junio C Hamano wrote:

Show 21 quoted lines

> 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