git branch diagram

git branch diagram

[Patrick.Higgins]

[-- Attachment #1: Type: text/plain, Size: 945 bytes --]

I am trying to get my employer to start using git and have found the distributed model and git's branching to be one of the hardest parts to explain and understand. I put together the attached diagram (done with graphviz so some things are not in the most logical place) to help explain things to my coworkers.

Unfortunately, I don't understand things well enough myself to know if the diagram is correct or not. I read in the stgit docs that developing directly in the master branch is discouraged by convention, but I don't really understand why. The git tutorial shows work happening directly in master, so I wasn't sure if that's a convention that only makes sense for stgit or for plain git, too.

In my diagram, I am assuming that most developers work in master, and make branches for their own long-lived projects and experimental things.

Does my diagram make sense? Are there any suggestions or corrections?

Thanks,
Patrick

[-- Attachment #2: git-branching.ps --]
[-- Type: application/postscript, Size: 27107 bytes --]

[-- Attachment #3: git-branching.dot --]
[-- Type: application/octet-stream, Size: 3136 bytes --]

digraph GIT
{
  node[shape = box];
  //clusterrank = none;
  ranksep=1;
  nodesep=.25;
  
  subgraph cluster_rel {
    label = "Release Repo";

    subgraph cluster_rel_t {
      label = "Tracking Branches";
      rel_im[label = "integration/master"];
    }

    subgraph cluster_rel_l {
      label = "Local Branches";
      rel_m[label = "master"];
    }
  }

  subgraph cluster_int {
    label = "Integration Repo";

    subgraph cluster_int_t {
      label = "Tracking Branches";
      int_p1m[label = "project1/master"];
      int_p2m[label = "project2/master"];
      int_p3m[label = "project3/master"];
    }

    subgraph cluster_int_l {
      label = "Local Branches";
      int_m[label = "master"];
    }
  }

  subgraph cluster_project {
    label = "Project Repo";

    subgraph cluster_prj_t {
      label = "Tracking Branches";
      prj_im[label = "integration/master"];
      prj_d1m[label = "dev1/master"];
      prj_d2m[label = "dev2/master"];
      prj_d3m[label = "dev3/master"];
    }

    subgraph cluster_prj_l {
      label = "Local Branches";
      prj_m[label = "master"];
    }
  }

  subgraph cluster_dev1 {
    label = "Dev 1 Repo";

    subgraph cluster_d1_t {
      label = "Tracking Branches";
      dev1_om[label = "origin/master"];
      dev1_d2[label = "dev2/master"];
    }

    subgraph cluster_d1_l {
      label = "Local Branches";
      dev1_m[label = "master"];
      dev1_e[label = "experimental"];
    }
  }

  subgraph cluster_dev2 {
    label = "Dev 2 Repo";

    subgraph cluster_d2_t {
      label = "Tracking Branches";
      dev2_om[label = "origin/master"];
      dev2_d1[label = "dev1/master"];
    }

    subgraph cluster_d2_l {
      label = "Local Branches";
      dev2_m[label = "master"];
    }
  }

  subgraph cluster_dev3 {
    label = "Dev 3 Repo";

    subgraph cluster_d3_t {
      label = "Tracking Branches";
      dev3_om[label = "origin/master"];
    }

    subgraph cluster_d3_l {
      label = "Local Branches";
      dev3_m[label = "master"];
      dev3_test[label = "mytest"];
    }
  }

  legend[shape=record, label="{GIT Branching|Intra-repo arrows are merges|Inter-repo arrows are pulls}"];

  prj_m -> dev1_om
  prj_m -> dev2_om
  prj_m -> dev3_om

  dev1_m -> prj_d1m
  dev2_m -> prj_d2m
  dev3_m -> prj_d3m

  dev1_m -> dev2_d1
  dev2_m -> dev1_d2

  prj_im  -> prj_m
  prj_d1m -> prj_m
  prj_d2m -> prj_m
  prj_d3m -> prj_m

  dev3_m -> dev3_test
  dev1_m -> dev1_e

  dev1_om -> dev1_m
  dev2_om -> dev2_m
  dev3_om -> dev3_m

  dev2_d1 -> dev2_m
  dev1_d2 -> dev1_e

  prj_m -> int_p1m
  int_p1m -> int_m
  int_p2m -> int_m
  int_p3m -> int_m

  int_m -> prj_im

  int_m -> rel_im
  rel_im -> rel_m [style=dotted,label="cherrypick"]

  release_builds[shape=doublecircle,label="Release Builds"];
  rel_m -> release_builds


  build_farm[shape=ellipse,label="Build Farm"]  
  project_builds[shape=doublecircle,label="Project Builds"];
  prj_m -> build_farm [style=dotted,label="on-commit"];
  build_farm -> project_builds

  project2[shape=plaintext];
  project3[shape=plaintext];

  project2 -> int_p2m [style=dotted];
  project3 -> int_p3m [style=dotted];
}

Re: git branch diagram

[Sitaram Chamarty]

[Patrick: apologies if you get this twice; the first time I did
"reply" instead of "reply all" and it only went to you, not the list.]

On Thu, Apr 17, 2008 at 10:30 PM,  <Patrick.Higgins@cexp.com> wrote:
>  Does my diagram make sense? Are there any suggestions or corrections?

Looks ok to me, but I'm still learning git myself... so beware of what I say :-)

Some quick comments:

The Project repo (the big one in the middle) need not, I think,
maintain long-lived tracking branches for every developer.  Rather,
that repo would pull based on outside-git inputs (analogous to emails
saying "please pull from ...") and there might be a temp tree created
to test stuff out but once the merge or cherry-pick into the local
master is done that temp tree would disappear

However, if you don't have too many devs then your method is fine too.

The problem with devs working on the same branch that the project repo
pulls is that the commits may have some cruft, even though you said
they'd make branches for experimental things.  The way I'm working
now, my "master" is clean as a whistle and anyone pulling from it and
merging gets exactly what is needed.

Again, this is not a rule, but personal preference and if your style
of working is very clean then this may not be needed.

Regards,

Sitaram

Re: git branch diagram

[Roman V. Shaposhnik]

On Thu, 2008-04-17 at 11:00 -0600, Patrick.Higgins@cexp.com wrote:
> I am trying to get my employer to start using git and have found the distributed model and git's 
> branching to be one of the hardest parts to explain and understand. I put together the attached 
> diagram (done with graphviz so some things are not in the most logical place)

Just as a usability comment: I believe that you should color-code or 
enumerate your arrows based on what part of the workflow they belong to.

> Unfortunately, I don't understand things well enough myself to know if the diagram is correct
> or not. I read in the stgit docs that developing directly in the master branch is discouraged 
> by convention, but I don't really understand why. The git tutorial shows work happening directly
> in master, so I wasn't sure if that's a convention that only makes sense for stgit or for plain
> git, too.
> 
> In my diagram, I am assuming that most developers work in master, and make branches for their own 
> long-lived projects and experimental things.

Speaking of diagram: when you say that inter-repo arrows are pulls, 
does it mean that you are not allowing developers to push their changes
back to the origin? If you're really trying to build your workflow  
around the pull-only, who does the pulling? IOW, who controls the
"Project Repo" (the big box in the middle)?

> Does my diagram make sense? Are there any suggestions or corrections?

Here are my comments (beware: they do not come from a Git guru, although
I'm trying to make my employer take Git seriously as well):
   * It looks like "Integration Repo" is really a Superproject that
     consists of submodules. Was that the intention?
   * do you really need dev[123]/master branches in the "Project Repo"?
   * I don't really understand what the smaller boxes labels "Local
     branches" are supposed to represent.

Thanks,
Roman.

Re: git branch diagram

[Karl Hasselström]

On 2008-04-17 11:00:56 -0600, Patrick.Higgins@cexp.com wrote:

> I read in the stgit docs that developing directly in the master
> branch is discouraged by convention, but I don't really understand
> why. The git tutorial shows work happening directly in master, so I
> wasn't sure if that's a convention that only makes sense for stgit
> or for plain git, too.

It doesn't even make sense for StGit. The documentation on the StGit
homepage that claims this ("As a convention, you should avoid working
in the 'master' branch of a remote project and use it only as a
reference, since it reflects someone else's work.") is simply
horribly, horribly outdated.

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle

Re: git branch diagram

[Fedor Sergeev]

On Thu, 17 Apr 2008, Patrick.Higgins@cexp.com wrote:
> I am trying to get my employer to start using git and have found the distributed model
> and git's branching to be one of the hardest parts to explain and understand.
> I put together the attached diagram (done with graphviz so some things
> are not in the most logical place) to help explain things to my coworkers.

One bit of advice - make at least two or three versions of this diagram,
with varying levels of complexity (say, complex one for integrators and 
simple one for developers).
Full diagram might appear to be very intimidating to newcomers :)

Depending on their background your coworkers might not like the whole idea
of branching (because of prior bad experience with branches and merges).
In my case the very word "branch" was not always accepted nicely.

My own experience in a similar situation (which has not yet been fully resolved,
so take my words with a grain of salt) shows that for the initial acceptance
it is better to devise a scheme that does not involve branching.

People will learn branching and will appreciate git's flexible branching 
in future, but for starters it might appear to be better to restrict amount of branches
to master + origin/master.

>
> Unfortunately, I don't understand things well enough myself to know if the diagram is correct or not.
> I read in the stgit docs that developing directly in the master branch
> is discouraged by convention, but I don't really understand why.
> The git tutorial shows work happening directly in master, so I wasn't
> sure if that's a convention that only makes sense for stgit or for plain git, too.

That is really up to your policies and your trust to the developers.
It is harder to screw up a master in Git than it is, say, in TeamWare.

But I would not let everybody in my project to freely go and do stuff in 
master. And I definitely would not make it a development requirement, as 
TeamWare background makes my coworkers shudder and sweat of a very thought
of touching master.

Your milage might definitely vary.

regards,
   Fedor.

Re: git branch diagram

[Matt Graham]

Full disclosure: I'm a git newbie.


On Thu, Apr 17, 2008 at 1:00 PM,  <Patrick.Higgins@cexp.com> wrote:
> I am trying to get my employer to start using git and have found the distributed model and git's branching to be one of the hardest parts to explain and understand. I put together the attached diagram (done with graphviz so some things are not in the most logical place) to help explain things to my coworkers.
>

A worthy goal.  It seems like a good corporate work flow for git is
either yet to be devised or yet to be documented.


>  In my diagram, I am assuming that most developers work in master, and make branches for their own long-lived projects and experimental things.
>
>  Does my diagram make sense? Are there any suggestions or corrections?

It feels more complicated than it needs to be.  My reaction is that
there should be a simpler way to represent it.

In the dev repos, do the remote branches and local branches have to be
in separate boxes?  It seems these could be put into a single box.

It's not clear who's doing the pulls into the project repository or
who is doing the integration.  My expectation would be that pushes
would be involved at some point, is it not necessary?

matt

Re: git branch diagram

[Jakub Narebski]

<Patrick.Higgins@cexp.com> writes:

> I am trying to get my employer to start using git and have found the
> distributed model and git's branching to be one of the hardest parts
> to explain and understand. 

Take a look at description of version control and distributed version
control at BetterExplained, and slides from presentations / seminars
which you can find in GitLinks page at git wiki.

> I put together the attached diagram (done with graphviz so some
> things are not in the most logical place) to help explain things to
> my coworkers.
> 
> Unfortunately, I don't understand things well enough myself to know
> if the diagram is correct or not. I read in the stgit docs that
> developing directly in the master branch is discouraged by
> convention, but I don't really understand why. The git tutorial
> shows work happening directly in master, so I wasn't sure if that's
> a convention that only makes sense for stgit or for plain git, too.
> 
> Does my diagram make sense? Are there any suggestions or corrections?

It is much too complicated. IMHO it would be better to explain the
idea of remote branches first (separate diagram), then simplify
diagram by showing only relationships between repositories:
relationship between branches is impled.

Perhaps adding what branches are supposed to be found at given
repository...

BTW. do all transfer is pull (or fetch) only, or are there pushes and
exchanging patches via email?

> In my diagram, I am assuming that most developers work in master,
> and make branches for their own long-lived projects and experimental
> things.

For example git itself, as a project, uses three long-lived branches:
'maint', 'master' and 'next', uses 'pu' (proposed updates) branch as
propagation / review mechanism for short-lived tipic branches.

-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: git branch diagram

[Matt Graham]

On Sun, Apr 20, 2008 at 8:30 PM, Jakub Narebski <jnareb@gmail.com> wrote:
> <Patrick.Higgins@cexp.com> writes:
>
>  > In my diagram, I am assuming that most developers work in master,
>  > and make branches for their own long-lived projects and experimental
>  > things.
>
>  For example git itself, as a project, uses three long-lived branches:
>  'maint', 'master' and 'next', uses 'pu' (proposed updates) branch as
>  propagation / review mechanism for short-lived tipic branches.

Jakub, could you explain the difference between maint and master?  And
the difference between master and next?  Maint and next are clear, but
how does master relate to those 2?

Re: git branch diagram

[Jakub Narebski]

On Monday, 21 April 2008, Matt Graham wrote:
> On Sun, Apr 20, 2008 at 8:30 PM, Jakub Narebski <jnareb@gmail.com> wrote:
>> <Patrick.Higgins@cexp.com> writes:
>>
>>> In my diagram, I am assuming that most developers work in master,
>>> and make branches for their own long-lived projects and experimental
>>> things.
>>
>> For example git itself, as a project, uses three long-lived branches:
>> 'maint', 'master' and 'next', uses 'pu' (proposed updates) branch as
>> propagation / review mechanism for short-lived tipic branches.
> 
> Jakub, could you explain the difference between maint and master?  And
> the difference between master and next?  Maint and next are clear, but
> how does master relate to those 2?

The posts titled "A note from the maintainer", posted around major git
release, should explain it. You can find them also at:
  http://git.or.cz/gitwiki/MaintNotes
  http://repo.or.cz/w/git.git?a=blob_plain;f=MaintNotes;hb=todo

In short, the minor releases like 1.5.3.8 are cut out of 'maint' branch,
the major releases like latest 1.5.5 are cut out of 'master' branch, and
'next' is where major part of development happens.

-- 
Jakub Narebski
Poland

Re: git branch diagram

[Luciano Rocha]

[-- Attachment #1: Type: text/plain, Size: 6262 bytes --]

On Mon, Apr 21, 2008 at 08:48:46AM -0400, Matt Graham wrote:
> On Sun, Apr 20, 2008 at 8:30 PM, Jakub Narebski <jnareb@gmail.com> wrote:
> > <Patrick.Higgins@cexp.com> writes:
> >
> >  > In my diagram, I am assuming that most developers work in master,
> >  > and make branches for their own long-lived projects and experimental
> >  > things.
> >
> >  For example git itself, as a project, uses three long-lived branches:
> >  'maint', 'master' and 'next', uses 'pu' (proposed updates) branch as
> >  propagation / review mechanism for short-lived tipic branches.
> 
> Jakub, could you explain the difference between maint and master?  And
> the difference between master and next?  Maint and next are clear, but
> how does master relate to those 2?

<quote from="maintainer">
There are four branches in git.git repository that track the
source tree of git: "master", "maint", "next", and "pu".  I may
add more maintenance branches (e.g. "maint-1.5.4") if we have
hugely backward incompatible feature updates in the future to keep
an older release alive; I may not, but the distributed nature of
git means any volunteer can run a stable-tree like that herself.

The "master" branch is meant to contain what are very well
tested and ready to be used in a production setting.  There
could occasionally be minor breakages or brown paper bag bugs
but they are not expected to be anything major, and more
importantly quickly and trivially fixable.  Every now and
then, a "feature release" is cut from the tip of this branch and
they typically are named with three dotted decimal digits.  The
last such release was 1.5.5 done on Apr 7th this year.  You
can expect that the tip of the "master" branch is always more
stable than any of the released versions.

Whenever a feature release is made, "maint" branch is forked off
from "master" at that point.  Obvious, safe and urgent fixes
after a feature release are applied to this branch and
maintenance releases are cut from it.  The maintenance releases
are named with four dotted decimal, named after the feature
release they are updates to; the last such release was 1.5.4.5.
New features never go to this branch.  This branch is also
merged into "master" to propagate the fixes forward.

A trivial and safe enhancement goes directly on top of "master".
A new development, either initiated by myself or more often by
somebody who found his or her own itch to scratch, does not
usually happen on "master", however.  Instead, a separate topic
branch is forked from the tip of "master", and it first is
tested in isolation; I may make minimum fixups at this point.
Usually there are a handful such topic branches that are running
ahead of "master" in git.git repository.  I do not publish the
tip of these branches in my public repository, however, partly
to keep the number of branches that downstream developers need
to worry about low, and primarily because I am lazy.

The quality of topic branches are judged primarily by the mailing list
discussions.  Some of them start out as "good idea but obviously is
broken in some areas (e.g. breaks the existing testsuite)" and then
with some more work (either by the original contributor's effort or
help from other people on the list) becomes "more or less done and can
now be tested by wider audience".  Luckily, most of them start out in
the latter, better shape.

The "next" branch is to merge and test topic branches in the
latter category.  In general, the branch always contains the tip
of "master".  It might not be quite rock-solid production ready,
but is expected to work more or less without major breakage.  I
usually use "next" version of git for my own work, so it cannot
be _that_ broken to prevent me from pushing the changes out.
The "next" branch is where new and exciting things take place.

The two branches "master" and "maint" are never rewound, and
"next" usually will not be either (this automatically means the
topics that have been merged into "next" are usually not
rebased, and you can find the tip of topic branches you are
interested in from the output of "git log next"). You should be
able to safely track them.

After a feature release is made from "master", however, "next"
will be rebuilt from the tip of "master" using the surviving
topics.  The commit that replaces the tip of the "next" will
have the identical tree, but it will have different ancestry
from the tip of "master".  An announcement will be made to warn
people about such a rebasing.

The "pu" (proposed updates) branch bundles all the remainder of
topic branches.  The "pu" branch, and topic branches that are
only in "pu", are subject to rebasing in general.  By the above
definition of how "next" works, you can tell that this branch
will contain quite experimental and obviously broken stuff.

When a topic that was in "pu" proves to be in testable shape, it
graduates to "next".  I do this with:

        git checkout next
        git merge that-topic-branch

Sometimes, an idea that looked promising turns out to be not so
good and the topic can be dropped from "pu" in such a case.

A topic that is in "next" is expected to be tweaked and fixed to
perfection before it is merged to "master" (that's why "master"
can be expected to stay very stable).  Similarly to the above, I
do it with this:

        git checkout master
        git merge that-topic-branch
        git branch -d that-topic-branch

Note that being in "next" is not a guarantee to appear in the
next release (being in "master" is such a guarantee, unless it
is later found seriously broken and reverted), or even in any
future release.  There even were cases that topics needed
reverting a few commits in them before graduating to "master",
or a topic that already was in "next" were entirely reverted
from "next" because fatal flaws were found in them later.

Starting from v1.5.0, "master" and "maint" have release notes
for the next release in Documentation/RelNotes-* files, so that
I do not have to run around summarizing what happened just
before the release.
</quote>

-- 
Luciano Rocha <luciano@eurotux.com>
Eurotux Informática, S.A. <http://www.eurotux.com/>

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]