search

iterative / cml.dev

🔗 CML website and documentation
https://cml.dev
Apache License 2.0
12 stars 23 forks source link

guide: branching strategies #196

Open casperdcl opened 2 years ago

casperdcl commented 2 years ago

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:

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

0x2b3bfa0 commented 2 years ago

More resources

flow

Click to reveal the source code of the diagram above... ```javascript const graphContainer = document.getElementById("graph-container"); const gitgraph = GitgraphJS.createGitgraph(graphContainer, {orientation: 'vertical-reverse', author: 'User '}); 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 '}) const second = experiment.branch("second"); second.commit({subject: "Add artifacts from the second experiment", author: 'Bot '}) experiment.merge(first, "Merge artifacts from the first experiment"); main.merge(experiment, "Merge improvements from the experiment branch"); ```
jendefig commented 2 years ago

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 commented 2 years ago

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

jorgeorpinel commented 2 years ago

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 commented 1 year ago

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

```mermaid
gitGraph
   commit
   commit
   branch develop
   commit
   commit
   commit
   checkout main
   commit
   commit
   merge develop
   commit
   commit
jendefig commented 1 year ago

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.

image
jorgeorpinel commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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

image

jendefig commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

indeed. Some non-obvious things:

jendefig commented 1 year ago

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 commented 1 year ago

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 🐰🕳️