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

From: Emily Shaffer <emilyshaffer@google.com>
Date: Apr 15, 2019, 17:26 UTC
Message-ID: <CAJoAoZkj_95ZWSGQ1Rpj02OAu==Wz=e4sFZnvuRr0dFQk3ZP8Q@mail.gmail.com>
In-Reply-To: <xmqq8swexy3v.fsf@gitster-ct.c.googlers.com>

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

Done.

Show 5 quoted lines

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

Sorry about that. I've found it's good practice to "show, don't tell" when I make review comments to avoid confusion, which isn't quite the same as "do it exactly like this" but looks similar on the box. So I guessed wrong this time. :) Will push a fix with it.

Show 17 quoted lines

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

In that case, I'd just as soon leave the order as it is. I think that a developer, outside of the context of a tutorial, will end up writing tests in the order they prefer regardless of the order of a tutorial they did one time. Maybe I can add a note about tests being required for incoming patches to discourage readers from glossing over that section.

>
> Thanks.