New Video: branches and merges without the guesswork

EvanReese

Hi everyone, I've been wanting to make this video for a while since I've seen so much confusion (including my own) around what branching and merging actually does. After playing around and experimenting with it a lot, I've finally come up with my own way of thinking about it that really makes sense to me, and I hope it can clear it up for anyone who is as confused as I was about it starting out. Let me know what you think!

https://youtu.be/XjdaRcD0faQ

bruce_williams

Nice job Evan! Interesting way of explaining merging as stacking the merged on top. I had not realized that it keeps things in order like that. Would be good to see how you think about and resolve conflicts. I use version and branches all the time, more for the risky trial only type things. Not really deep diving into team use and other ways to use power of branch/version.

EvanReese

bruce_williams said:

Nice job Evan! Interesting way of explaining merging as stacking the merged on top. I had not realized that it keeps things in order like that. Would be good to see how you think about and resolve conflicts. I use version and branches all the time, more for the risky trial only type things. Not really deep diving into team use and other ways to use power of branch/version.

If that's not how it works I really hope someone from Onshape lets me know before too many people watch the video. Do you have an example of a conflict you may have run into? I think if everyone just keeps each branch contained to just one general idea at a time there's usually not much issue.

ilya_baran

Thanks for doing this, Evan!  That's a really good explanation.  There isn't anything to correct, but I can add a couple of things for completeness:
1. I would mention that versions aren't just for branching and "notable points" but also needed if you want to reference that point in history (either from the current document or another document).
2. As you showed, there conflicts are resolved automatically; I'd say this is a limitation of the current merge functionality because if someone made the part purple on one branch and green on the other, it'd be nice to know when one of these changes is being overwritten, but we don't have a mechanism for that yet.
3. The whole microversion concept is analogous to how a git repository works (we took the ideas from there).  I assume you've read this, but just in case: https://www.onshape.com/en/resource-center/articles/under-the-hood-how-collaboration-works
4. Where your "changes on one branch go after changes on the other" explanation breaks down is if you make a second merge from the same branch.  We will not merge changes that have already been merged (although if you restore to a state before the merge, the next merge *will* merge those changes again).  The real algorithm is even more involved than that, but the point is for multiple people to be able to work each on their own branch, periodically merging main into their own branch and merging their changes into main.  Once we gain the ability to show merge lines, hopefully this will become clearer...

john_mcclary

@Evan_Reese
Nice video, That even cleared a few things up for me. I still have fears of people who don't have a good understanding of the branching/merging haphazardly mucking everything up. There have been a few cases at work where people were detailing or referencing the wrong branches.

This is comprehensive and short enough, I may just get people at work to watch it.
I'm going to keep this video as part of my training tools while we try and replace SolidWorks.

Hopefully one day Onshape makes it a bit clearer when opening a workspace. Maybe a blinking, animated, or vibrant color for the workspace name that stops after the user has shown activity for a few seconds. (incase they loaded the page and walked away for a coffee)

EvanReese

@ilya_baran
Thanks so much for watching and adding more clarity. I'd love better ways to visualize which change overwrites others. I've thought it would be nice for the merge step to be expandable to reveal all of the steps to get there, and even view those microversions, but maybe that isn't possible with your current architecture. According to your article (which I hadn't read, so thanks!) the merge is itself a microversion, so maybe we'd be talking about nano-versions by this point. By the way, I liked the bit you wrote about why undo is a microversion itself. I'd always wondered that, and it makes sense. I will say, did make it a personal point to not use the word "git" in the video, since people who know git, probably aren't the ones who need a video like this. That and I've never used it either  . Point 4 you make is somehow intuitive to me, but I couldn't explain why to someone, so I've got to think on it. Anyway, thanks for chiming in!

EvanReese

@john_mcclary
Maybe something subtle like so? Would be nice if the admin could activate it for only certain users. Sloppy use of branches in a document in which I'm also working is definitely a phobia of mine.

But for real, I'm glad you found it useful. Good luck with your SW replacement scheme!

john_mcclary

Even I miss what branch i'm in now and then, it's just such an invisible thing from the corner of your eye

EvanReese

john_mcclary said:

Even I miss what branch i'm in now and then, it's just such an invisible thing from the corner of your eye

Absolutely. Me too. I really like your suggestion of something more obvious until you begin interacting. I know it would save me from time to time.

fnxf

Hey @Evan_Reese, great video! I've explained merging and branching to a many colleagues, yet your video pulls it all together very nicely. I liked your explanation of workspaces, because that's where you "work"- :lightbulb: Also the point about deleting branches to clean up, that's a good one. 
I've said "last one wins" when merging, but as @ilya_baran points out, when merging multiple times it's not as simple. Also.. am I reading too much into what ilya_baran said:

Once we gain the ability to show merge lines, hopefully this will become clearer...

I really hope we gain this ability soon 😀 

And about naming of versions, workspaces and merged branches, my conventions are as follows:

1. Always let the V of the version stand, e.g. V4, but add an explanation behind if necessary (i.e. big change) e.g. V4: new lightweight wings
2. Always let the B of the branch stand, e.g. B3, but add context, e.g. B3: trial of flexible wings
3. Before merging, create a version in that branch, e.g. V5
4. Merge V5 into Main, that creates a microversion in Main called "Merge from V5"
   
5. Rename the branch where V5 was in to "merged | B3: trial of flexible wings" so it's easy to see after an update has pulled all branches to the top

Now I am off to see what the new update has in store for us!

EvanReese

@fnxf
Thanks! I got the bug to make this video after trying to explain it to some employees who were coming from Solidworks. Even with slides prepared I just had a tough time, but I knew if I took the time to loosely script it and pair it with animations, I'd be able to get it across concisely enough.

On naming conventions, I leave the V (e.g. V4), but I've stopped leaving the B in favor of a descriptive name. When you delete branches it doesn't work automatically anymore. It seems like the naming algorithm just counts the number of active workspaces and adds one, but since I delete mine, my 6th branch could still autofill as B1, and I don't want to bother figuring it out manually. It feels right to me anyway. After all, "Main" could have been called "B0" but that's not very descriptive.

I do your steps 3-5, generally. If it's an important merge, I take the time. If it's something tiny, I don't. My personal nomenclature for merges is flexible wings -> Main so that I could also use it to capture merges between branches (e.g. flexible wings -> perforated wings). "merged" is probably enough to imply "merged to Main" though, I rarely merge anywhere else.

Onshape team, I'm sure I've submitted a request for this at least once, but it would be really wonderful to give user options on whether to version and delete the branch while merging all at once. In fact, I'd also use an option that automatically makes a version in both branches, especially in lieu of merge lines. And, of course, as has already been mentioned, add merge lines.