Re: [PATCH 1/1] documentation: add lab for first contribution

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 13, 2019, 05:39 UTC
Message-ID: <xmqq8swexy3v.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <CAJoAoZnY8hQmxPBcFFZEonQvMLT6x2xrfupy7+gcu+uUN1h1cg@mail.gmail.com>

Emily Shaffer <emilyshaffer@google.com> writes:

> I like this suggestion, but don't like the use of "fork" as it
> somewhat conflates
> a GitHub-specific term. I'll take this recommendation but use "create" instead
> of "fork".

The verb "create" is not incorrect per-se. It stops at saying that the result points at the commit that happened to be at the tip of the original when it was created. But it lacks the connotation that the resulting branch also knows that it is meant to eventually be merged back to the line of history of the original, which "fork" conveys.

The word "fork" is pretty well established in that context of talking about a branch, in the form of "--fork-point" option of "git rebase". It is the point where a side branch diverged from the mainline.

So I dunno.

        Side note. By the way "fork" is in no way GitHub specific.
        A random list archive search gives us this from 2007 but I
        am reasonably sure that Linus kept using the word before I
        took the maintainership over, in the context of talking
        about "distributed nature of Git makes the 'maintainer'
        honest, by allowing others to fork and become the mainstream
        if the maintainer does a bad job".

        http://public-inbox.org/git/alpine.LFD.0.98.0705010829180.3808@woody.linux-foundation.org/

        So it is fairly well understood what "fork" means in the
        project management sense around here in the Git project.

        In any case, that is a tangent.  That possible "conflation"
        is about forking the whole repository, but the example is
        talking about getting a single new branch to work on, so in
        a sense it is an apples-and-oranges comparison.

Show 7 quoted lines

>> ... then leave it in your example, perhaps?
>>
>
> Good point. :)  I had wanted to avoid including my own name/email in the
> tutorial; I used a throwaway "Git Contributor <very@smart.dev>" for the example.
> ...
>> Keep a sample sign-off by "A U Thor <author@example.com>" here.

No, use "A U Thor <author@example.com>" as I suggested. That's the author ident the aspiring Git developer MUST become familiar with while working with our test suite in t/. There you will also find the counterpart committer ident to use, if needed.

Just FYI, I rarely give a "do it exactly like this" suggestion; often I instead stop at giving a general direction and leave it up to the contributers to perfect it. The "A U Thor" is one of those rare cases. On the other hand, "fork" was *not*.

> Do folks on Git project usually engage in test-driven development? I
> would be happy to move the test up towards the front of the document
> and mention the usefulness of TDD, but not if that's not something
> emphasized usually by the group..

I have no strong opinion on this myself.

I suspect that the developer would clean up with "rebase -i" by squashing before submitting the result of a very fine-grained TDD workflow, as nobody would want to read printf("hello world") in [PATCH 1/47] that would become a real feature in a later step. So if the tutorial wants to go into that tangent (which might be too much detail), it may be worth showing from the first few commits, but otherwise a sequence that pretends the reader to be a perfect developer who does not make any mistake in the middle may be more concise and more readable. I dunno.

Thanks.