When does it make sense to use subrepositories?

[Isaac Jurado]

Replying v:
>
> I've just backed out of several hours' work transitioning a set of
> related projects from one repository to a group of subrepositories.
> Having been through this a few times before, I always seem to end up
> with one of two scenarios:
>
> - If changes to one project are usually associated with changes to
>   other related projects, put them in the same repository.
> - Otherwise, use separate repositories, and handle the relationship with you
>   favourite dependency management solution. If you really want to do
>   this with your SCM, then use guestrepos.
>
> I do acknowledge that subrepos are now declared "a feature of last
> resort", but I'm wondering what this situation is. Someone paid for
> them to be developed, so they must be useful somewhere!

In my previous work we were using them, and I can say it was a success
story.  Of course, not without some trouble.  Subrepositories are
specially problematic when combined with history edition, which could
lead you to being unable to cleanly checkout a particular revision.

I believe our story is the typical growing busniness story: a project is
started (say ProjA), some kind of framework is inadvertently built up,
and then someone decides that the work can be reused for a new project
(say ProjB).  When developing under the shadow, proper packaging and
decoupling is the last of the concerns; as long as it deploys smoothly
enough, no further progress is done in that regard.

Even though we were lucky enough to put all the shareable stuff inside a
single subdirectory, our first approach to this situation was a
copy-paste-fix-commit cycle.  After a month, the guy in charge of that
task came to me and desperately begged for a better solution.  So I set
up a subrepository for the subdirectory and that saved our day.

After learning some lessons from a couple of mistakes, we ended up with
a usable workflow:

    - Each project using the framework followed the same directory
      structure.  In particular, the subrepository was always the same
      directory (say lib/).

    - Each project had its own branch of the subrepository.  So we had
      lib-ProjA, lib-ProjB.  These were clone branches, not named
      branches.  This way, each project could modify parts of the
      library without interfering the other projects, but the
      "libraries" were still _mergeable_ (if that's a word) for the
      times we dedicated to sync the different library versions.

    - The project repositories used standard branching (default/stable
      named branches, same as Mercurial itself), but the subrepositories
      did not.  Instead, we allowed the lib-* repositories to have
      multiple heads.  Because of this, sometimes we had to "push -f".

And I must say it worked really well for us.  Specially considering that
I was the only one with some real interest in version control.  Two of
them explicitly requested to have merge tools disabled and instead being
asked to pick one file out of three, because they were scared of seeing
three or four pane windows (meld, kdiff3):

    [ui]
    merge = internal:prompt

That setting actually generated more problems than the subrepositories.

So finally, yes, subrepositories cause trouble but it is possible to
make them work in some ways.  My advice is: be sure you understand them
deeply before attempting anything fancy because the first response of
subrepository related help request is always the same; don't use them.

Cheers.

-- 
Isaac Jurado

"The noblest pleasure is the joy of understanding."
                                  Leonardo da Vinci