Re: [PATCH 1/1] documentation: add lab for first contribution
- Date: Mon, 15 Apr 2019 10:26:02 -0700
- From: Emily Shaffer <emilyshaffer@xxxxxxxxxx>
- Subject: Re: [PATCH 1/1] documentation: add lab for first contribution
> >> ... 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@xxxxxxxxx>" for the example.
> > ...
> >> Keep a sample sign-off by "A U Thor <author@xxxxxxxxxxx>" here.
> No, use "A U Thor <author@xxxxxxxxxxx>" 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*.
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.
> > 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
outside of the context of a tutorial, will end up writing tests in the
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.