guide: branching strategies

[casperdcl]

Diagrams and guide for collaborative branching strategies (e.g. using cml pr for experiments in a large team, reporting, rebase vs squash-merging, hiding unneeded rows in Studio, etc.)

Also saving results https://stackoverflow.com/a/74563657/3896283

Also should mention caveats (e.g. cascading/nested PRs obscures reports).

Related resources:

• https://stackoverflow.com/a/70205896
• https://github.com/iterative/viewer/issues/3157
• https://github.com/iterative/example-get-started/pull/31
• https://discord.com/channels/485586884165107732/1073560646718849034/1073586419907448933 (on: workflow_dispatch, commit message [skip-ci], if: contains(github.event.head_commit.message, '[trigger]'))

Related issues (potentially duplicates and/or sub-issues):

• [x] https://github.com/iterative/cml/issues/656
• [ ] https://github.com/iterative/cml/issues/1126
• [ ] #393
• [ ] #390

[0x2b3bfa0]

More resources

• https://www.notion.so/iterative/Result-commits-2f12535f290743ea9bb6fdb27009f920
• https://www.notion.so/iterative/Ancillary-pull-requests-51110e5c3ef0437ba0fc59b22ebf015f
• https://www.notion.so/iterative/Prototype-0b6a441d00dc4956b0b6899c9e96543e

Click to reveal the source code of the diagram above...

const graphContainer = document.getElementById("graph-container");
const gitgraph = GitgraphJS.createGitgraph(graphContainer, {orientation: 'vertical-reverse', author: 'User <name@domain>'});

const main = gitgraph.branch("main");
main.commit("Initial commit");

const experiment = gitgraph.branch("experiment");
experiment.commit("Launch two experiments");

const first = experiment.branch("first");
first.commit({subject: "Add artifacts from the first experiment", author: 'Bot <runner@machine>'})
const second = experiment.branch("second");
second.commit({subject: "Add artifacts from the second experiment", author: 'Bot <runner@machine>'})

experiment.merge(first, "Merge artifacts from the first experiment");
main.merge(experiment, "Merge improvements from the experiment branch");

[jendefig]

I have a backlog item in my tasks "review this material for CML diagrams" pointing to this issue. Not sure why. Do you need this diagram recreated for docs or use case?

[casperdcl]

I think this is more a @iterative/docs issue than a devrel one

[jorgeorpinel]

I'd call this a p1 instead of an epic, at least from the description and within my understanding of what those labels mean.

[casperdcl]

useful mentioned by @mjasion: https://mermaid-js.github.io/mermaid/#/gitgraph

```mermaid
gitGraph
   commit
   commit
   branch develop
   commit
   commit
   commit
   checkout main
   commit
   commit
   merge develop
   commit
   commit
```

gitGraph
   commit
   commit
   branch develop
   commit
   commit
   commit
   checkout main
   commit
   commit
   merge develop
   commit
   commit

[jendefig]

Question: what is happening in this part of the picture? why does checkout main pop up into that middle section between develop and main? When I checkout out to main, I'm not really on main, but in some kind of limbo? I'm not having an opinion on anything here. Just trying to legitimately understand. Been studying Pro Git. 😊 I was thinking when I checkout to main that I actually go back to main, but now I'm not sure.

[jorgeorpinel]

Where are you seeing that figure, @jendefig ?

checkout only moves you to some branch, so to speak, to act on it. It doesn't cause any change to the graph.

[jendefig]

In what @casperdcl put above from Mermaid. Do you see how it shows the line in the middle space? I thought that if I checkout I'm essentially jumping from one to the other. Is that right or wrong?

[jorgeorpinel]

Ah right (weird, the hashes seemed to change, anyhow...).

It's just how this particular graph is rendered (corresponds to the 2nd merge). There are no commits in that line i.e. it's not another branch.

if I checkout I'm essentially jumping from one to the other

You could say so. In reality the latest commit of the checked out branch is restored into your working tree (what you see in the repo directory). See https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging

p.s. I'm hiding these comments as off-topic but feel free to reach out directly with Qs on this 🙂

[casperdcl]

@jendefig actually raises a gewd point - someone new to Git graphs won't find the git command <> graph node mapping 100% intuitive.

[jendefig]

Thanks for this @casperdcl! This is how I was understanding how everything lined up. So is the blue line extending back to the develop branch because the merge occurred from the main branch. But if the merge occurred off the develop branch it would be yellow/chartreuse? Testing...

gitGraph
   commit
   commit
   branch develop
   commit
   commit
   commit
   checkout main
   commit
   commit
   checkout develop
   merge main
   commit
   commit

[jendefig]

Ok. I get it now. You are jumping when you checkout. The in-between lines are representing where the merge is coming from. Git is like being in a Christopher Nolan movie. 💡

[casperdcl]

indeed. Some non-obvious things:

• line colours don't really have much meaning, especially colours of vertical lines between branches (corresponding to checkout/merge)
  • strictly speaking the line colours indicate which branch you were on before running commit/merge... but 'tis neither intuitive nor particularly useful info IMO
• implicit arrow of time points from left to right (a concept literally used in quantum physics)
  • as commit number prefixes N- increase
• merge commands are "special" commits that have at least 2 parents
  • since merges are commits, they should have a (N- prefixed) commit hash. This is missing (ARGH!)
• a commit can exist in multiple branch histories. A "branch" is really just a label that can be moved to any commit. In fact each time you "add a commit to a branch" you really "add a commit on top of the existing one, then update the branch label to point to the new commit"

[jendefig]

Re: Color

I think it might be nice to have a generally agreed upon color for the main branch, but that's out of our control.

merge commands are "special" commits that have at least 2 parents

So the merge commit parents are the main and dev branches and the commit will appear in both, is that right?

• since merges are commits, they should have a (N- prefixed) commit hash. This is missing (ARGH!)

ARGH x 2

a commit can exist in multiple branch histories. A "branch" is really just a label that can be moved to any commit. In fact each time you "add a commit to a branch" you really "add a commit on top of the existing one, then update the branch label to point to the new commit"

When you say "a label," just confirming you are using the term in a general sense, not at all referring to labels in GH, right? The label is the branch name, did I understand this correctly?

Thanks for these explanations! 🙏

[casperdcl]

merge commit parents are the main and dev branches

more accurate: merge commit parents are a particular pair of commits on the main and dev branches

and the [merge] commit will appear in both

no, the merge commit only appears in the target (main) branch, not the source (dev) branch

When you say "a label," just confirming you are using the term in a general sense

yes, in this case I mean "a label" in the general sense, as in "a human-readable name/alias for a commit hash". Git branches and Git tags are just aliases.

In fact a tag is identical a branch. We just (usually) assume tags are not meant to be moved/updated (use case: version numbers, tag v1.0.3 always refers to one commit) but branches are meant to be moved/updated (branch main is constantly updated to point to different commits).[^1]

[^1]: there do exist some super-advanced scenarios that break this assumption 🐰🕳️