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

[Junio C Hamano <gitster@pobox.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.

>> ... 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.