[ccan] could you put the license on the download page?

[Avery Pennarun]

On Sun, Oct 24, 2010 at 5:59 PM, Rusty Russell <rusty at rustcorp.com.au> wrote:
> I've split and created my tree; what's the workflow for someone who wants
> to modify a module?
>
> They really want to do their work in the full tree (which contains the
> tools and any other modules they need),

Note that there's one interesting thing you might not have noticed
here: it's not necessary at all for a contributor, who wants to work
in the full tree, to split things out himself; you can have one person
who does all that.  This is a nice advantage of git-subtree compared
to git-submodule.

>        # Fresh working branch...
>        git checkout -b my-mods master
>        # hack hack hack
>        git commit -a -m "improve foobar"
>        git commit -a -m "improve foobar more"
>        # put those into the module-foo branch
>        git subtree split -P ccan/foo -b module-foo --annotate "foo: " master

I've found that most people don't actually use --annotate.  This is
probably especially true in this case; you would rarely annotate the
commits of the 'foo' project with an extra 'foo:' prefix.

But otherwise, ok so far.

>        # Throw away commits from this tree.
>        git reset --hard master
>
> The reset seems tacky and a bit dangerous.  It'd be nice if subtree split had
> a --discard which removed hunks and removed entire commits if they were empty.
>
> In fact, that would be really nice for splitting the project into subtrees
> in the first place...

This part isn't what people normally do.  Basically, git-subtree has
two modes: --squash and the default.  Personally I prefer --squash,
and it seems other do too.  (Perhaps if I had invented that mode
first, we wouldn't have had the original/default behaviour.)

Also, in the use cases I've seen, people don't submit stuff upstream
right away; they want to test out their stuff in the merged project,
sometimes for months, and then submit patches upstream afterwards.

Furthermore, you might want to rebase the patches after splitting them
out, in the hopes that upstream will actually accept them.  That means
what happened in your merged project isn't necessarily what will
happen in the upstream project.

Thus, the "most honest" way to represent history is to *not* just
remove the old commits from the joined tree.  Instead, you split them
out, rebase them if necessary, submit them upstream, and merge the new
upstream version back in.

The result is that your merged history now has the same changes (or
similar ones) *twice*.  But this is okay, because it's the truth: it
precisely reflects exactly what happened.

Now, back to the --squash.  If you're using --squash, then you won't
re-import the changelogs from the split project back into your main
project.  That keeps your 'git log' in the main project clean,
although it somewhat reduces the detail level in your log, which could
theoretically be useful for bisecting or something.  Most people don't
care about that; in fact, most people would rather have 'git bisect'
just consider pre-merge and post-merge as two points in the history of
the main project, rather that considering every revision of every
subproject.

So anyway: the answer is, do it like you were saying, but skip that
'git reset' line, and all should be well.  You can safely merge your
changes into the mainline branch of the main project, *and* split them
and submit them upstream, and you should be fine.

Does that make sense?

Have fun,

Avery