Re: Recommended work flow with git to send in patches

[Jakub Narebski <jnareb@gmail.com>]

On Thu, Jul 29, 2010, Tong Sun wrote:
> On Tue, Jul 27, 2010 at 1:35 PM, Jakub Narebski <jnareb@gmail.com> wrote:
> 
>>> First of all, philosophy for version control with git:
>>>
>>> . While developing, small/independent commits are good thing, so that
>>>   it's easy to decouple different changes.
>>>
>>> . But when integrating something in a main branch, commits should contain all
>>>   logical/related changes.
>>
>> I think that in final results, i.e. in patches that you send, or
>> commits that you send pull request for, you should have commits that
>> do one thing, and do it completely and without breaking.  Nevertheless
>> having small commits that you publish / send to maintainer is a good
>> thing; it is always easy to review a few small patches, than one
>> mage-patch.
> 
> Yeah, that's actually exactly what I believed before getting feedbacks
> from grml developers for squashed patches. It's an interesting topic
> to me, so let's dig deeper into it.
> 
> Say that I need to add a feature to a CLI program. I would
> instinctively divide it into 3 logical steps/patches, 1st to the user
> interface (the command line handling), 2nd to the implementation, and
> 3rd to the document.
> 
> Do you think 3 small patches is the way to go, or a single patch is,
> since all 3 are logically related?

In this situation it is obvious to me that you should send single
squashed patch, as otherwise commit does not contain all related and
connected changes: command line handling without implementation doesn't
make sense, and if you are implementing something, you should document
it.


An example of change that might, or might be not split into two commits
is simple bug fix.  You can either first write failing test showing the
breakage, and then write fix and change test expectation to pass, or you
can write fix and test in one commit.

Here are a few generalized examples from git repository history where
you might want to send a change as a series of patches rather than in
one large single patch:

1. If you are improving documentation, you can split your patch into
   one adding missing documentation for some feature, and second adding
   examples of using said feature.

2. If you plan to make some part of code used more widely, you can in
   first commit make API public, in second add support for feature to
   wider codebase, and in third add tests for this support.

   Similar thing with having doing refactoring first, then using this
   refactoring to easy add new feature.

3. If you are fixing some compiler warnings, fixing each class/type
   of warnings could be made into separate commits.

4. You can have one commit adding feature, and second adding support
   for said feature (for parameters / subcommands that use said feature)
   to shell completion.

Etc.

> Now back to our topic, thanks for your work flow explanation, I'll
> answer/ask in this single message.
> 
>> Why not git-clone (possibly shallow, if you are working on one-shot
>> patch or patch series)?
>>>
>>> Ok, to explain it, I have to touch upon my "life long story" of using
>>> git.
> 
>> I don't understand this second step.  Why do you want this second clone?
> 
> That's what I searched and found from the Inet when I was looking for
> the recommended work flow, which was to do 'git clone' from web once
> then 'git clone' several local working copies to work on several
> independent unrelated features. Now I know creating my own local
> branches is the way to go.

I think "fork (clone) to branch" was from some very ancient git tutorials
(git has in-place branching and branch switching from time immemorial),
or from some (outdated?) Mercurial documentation.

That said shallow clone should be improved, so you can clone from
shallow clone with the same depth or shallower.  Current implementation
is a bit lacking.

>> If you plan to continue working on this repository, and it is not
>> one-shot patch or patch series, it would be better (easier in the
>> future) to use "git remote add".
> 
> Could you elaborate more on this with git commands please, so that I
> can have a full picture?
> 
> Thanks again for your clearly explanations, I think I don't any
> further questions for the moment.

I don't think that would apply in your situation, but "git remote add"
is used if you want to fetch changes from more than one upstream repository
(or you want to configure repository to push into).  This is an alternative
to one-shot "git pull <URL> <branch>" which does not save _any_ information
about upstream you fetched (pulled) from.

See git-remote manpage for details.
-- 
Jakub Narebski
Poland