Versioning Philosophy in Onshape

StephenG

When I started using Onshape versioning of documents didn't make complete sense to me. I tabled my concerns thinking, that with use, Onshape's versioning philosophy would eventually make sense. It has been 2 years now and I still fail to grasp why Onshape choose to do versioning at the document level, as opposed to at the element/tab level. To be honest my prior CAD experience versioning was done at a lower data (Part, Assembly, Drawing, etc.) level, so my brain kind of got wired to think in that way. I am still holding to idea that versioning individual things in a document as opposed to everything that has changed in the document is better. 

I would like for someone at Onshape, who was party to the decision to do versioning at the document level, attempt to set me straight, convince me, that versioning at the document level is a superior versioning method.   

konstantin_shiriazdanov

I'm not from Onshape but it may be because everything on the document level is synchronized by default, you don't need to care from which version of part studio you use the parts. You don't have infinite forum postst asking "i restored my part sdudio version, but assembly didn't changed, is this a bug? " Also possibly it was just easier to implement in "everything or nothing" paradigm.

tim_hess427

@StephenG - I think the thing you're looking for is the Revision. 

While the "version" is a snapshot of the document in time, and provides a way to reference the entire document (or an element of that document) from some point in its history, a Revision is an element level (part, drawing, assembly) design control mechanism. 

So, the functionality you're looking for exists, but the terminology may be a little different. 

adrian_vlzkz

I'm on the same boat @StephenG, 

Let's say I have a Document with 10 tabs and I go ahead and change one of them. I'm happy with the change so to capture it, I create a new version... well what just happened is that I just versioned 9 Elements that DID NOT CHANGE. To me that is not a good Data Management practice, and creates a lot of overhead keeping track of what's changing and what's not.

The same goes for Branching, I'd like to be able to Branch a single element(tab) not the entire Doc.

rob_rowland

I agree with @StephenG and @adrian_vlzkz.   Versioning at the document level is confusing.   
Another user on the forum likened it to having a 100 bookmarks in a book.  Once you have more than a few unimportant bookmarks in the book, the point of the bookmark is lost...

owen_sparks

tim_hess427 said:

@StephenG - I think the thing you're looking for is the Revision. 

While the "version" is a snapshot of the document in time, and provides a way to reference the entire document (or an element of that document) from some point in its history, a Revision is an element level (part, drawing, assembly) design control mechanism. 

So, the functionality you're looking for exists, but the terminology may be a little different. 

THIS ^^^

As pro users you have access to this today...

Owen S.

michael_bromley

I would agree that "revision" is what you are looking for and it is part of the release management process.  However, the one caveat to this and the part I still struggle with is that anytime you want to create a revision it also creates a version of the overall document.  This muddies the waters in my opinion and makes it difficult to navigate through the document.

tim_hess427

@michael_bromley - Agreed! While revision does you the ability to control the evolution of individual elements, finding those specific revisions and working with them still has room for improvement. 

BulletEngineering

I have a bit of a software background and find the Onshape versioning philosophy quite intuitive - it is the same process used for software release management. The whole point is to have each 'version' to be a functional snapshot with all changes integrated. A version is a standalone chunk that represents a major or minor release and can be treated as a complete whole. Admittedly, it is not a good tool for tracking individual changes without good notes for each version, but that is also a software habit that supports the philosophy.

From a data perspective, deduplication and a sparse database prevents the overhead from bloating past a few wasted bits; a small cost for the advantage of a very powerful tool.

The OnShape team wrote an excellent learning article on the subject: https://learn.onshape.com/learn/article/gitflow-version-management

  

BulletEngineering

In our company, the version approach is also useful as a communication tool between Engineering and Manufacturing: Each time a part is updated, we create a new version named "Production" + (Date of version). The guys on the shop floor can open the version manager and jump to any date in the past and view the parts and drawings that were released for production at that time.

The case comes up when a machinist checks the last run of a part, finding it came from sometime last year. He can quickly pull up the corresponding version, and compare it with the most recent to determine the portions of GCode he needs to re-write (or re-post). Rev notes on drawings help, but a quick geometry check can save hours of deciphering chained change notes.

adrian_vlzkz

@BulletEngineering I don't believe the method itself is the problem, I find it intuitive as well. The problem is that Versioning happens at the Document level. It needs to be more granular, at least at the Element (Tab).

tim_hess427

@BulletEngineering - I've thought about trying to do something similar, but it seems like it works best if there is a 1-to-1 relationship between the version and the items being released, right? Does that still work if you have standard parts that are used in multiple documents? 

One way I've thought about doing things is to great whatever number of documents is needed during design and development. Then, create my "Release Document" that has the top level assembly. This top level assembly can be linked to all of the most recent part revisions. The problem with this is that I wouldn't know where to put my drawings. Should they go in the release document with the assembly? Or should they stay in the same documents at their parts? I can make arguments in my head for each (until Onshape allows us to link a read-only drawing into a new document). 

michael_bromley

After reading @philip_thomas reply in this thread:

https://forum.onshape.com/discussion/12163/how-many-part-studios-would-too-many-per-document#latest

The versioning/release would make a bit more sense if you truly only had one part studio and one assembly per document.  I think you are onto somethin @tim_hess427 that you would have a document for the top level assembly.  It seems to me that the drawings would all live in their own documents and only the top level assembly drawing is in the top level document.  I think the area where this breaks down potentially is it could get quite cumbersome to navigate when there are many levels to an assembly.  I'm very curious to try it now.

For some background, we currently use a document to contain everything for a project.  For example, when design custom machinery all of the part studios, sub assemblies, top level assemblies, and drawings are contained in a single document.  This can not only get unwieldy, but makes the versioning system pretty much useless since it is so broad.

philip_thomas

These are all awesome threads and we all read them.
Just to be clear - a version is nothing! It is a marker that helps the designer create reference points in the development of a Document. It is a jumping off point for branches and makes comparing two points in time easier. They are free, easy and convenient - that said, they have NOTHING to do with release management (revisioning) as they apply to the whole Document. Release management applies to a part, assembly, drawing or blob and uniquely identifies a piece of data at a revision level. Moreover, revisions significantly reduce the level of false positives when an assembly (for instance) references a version and someone versions the document containing the referenced part.
The article referenced suggests only that the contents of a document represent the logical units one would use to share to an outside source - I am NOT advocating one part per document necessarily.

Bottom line - versions are to help the designer (think 'saves'), revisions are for the company and the rigor of engineering process

michael_bromley

@philip_thomas I understand mostly.  My only point of confusion is that although a version is not always a release, a release is always a version of the document.  Therefore from a high level it takes digging into each release to figure out what had happened since there are currently no good high level views.  This becomes easier if the large document is broken out into many smaller more granular documents.  

tim_hess427

@philip_thomas - thanks for the insight. I was talking the other day to someone about how responsive your team is and its really appreciated. 

@michael_bromley - this comment got me thinking, especially this part: "from a high level it takes digging into each release to figure out what had happened". 

You could potentially say the same thing about a version, couldn't you? "from a high level it takes digging into each version to figure out what happened", especially if the document has many part studios, assemblies, branches, etc..  

Continuing down that path... If I want to know what happened in a particular release, I know can open up the "release candidate" by right-clicking on the triangle in the version tree and seeing exactly what was released. Part of the problem for me, I think, is that Onshape gives me a very "document-centric" perspective, which is perhaps good for design workflow, but not so good for review, inspection, and design-control workflows. The only way of getting to the release candidate information (that I can think of) is by first finding the right document and opening its version tree. 

If I'm thinking about project management and design control, I have a part and assembly perspective in my head. I'm asking myself: which parts are unreleased still? What is the most recent version of Part Number X? What is the design history of Part number X? Where is part number X used? For me, these are the questions that are hard to answer. And for me, its not a document/version/revision issue - its a search or "main page" issue. I know some of this stuff can be found using the right search parameters, but it still doesn't seem intuitive or hasn't quite "clicked" for me yet. It also still bugs me that part numbers aren't shown in search results - that just seems like a no-brainer to me. 

michael_bromley

@tim_hess427 Yes I agree and you make valid points.  That is one of the benefits I see to using a much more granular document structure.  Having not tried it yet I'm not sure what downsides it has.  I'm assuming navigating could become more cumbersome as you would constantly be opening alternate documents.

The upside in this granular document structure (one part studio and one assembly studio) is that the version tree and releases may make more sense as the document is much more focused.

Lastly, I agree that we need a way to view the document status at a high level which is probably a different subject than versioning itself.

adrian_vlzkz

tim_hess427 said:

 
Continuing down that path... If I want to know what happened in a particular release, I know can open up the "release candidate" by right-clicking on the triangle in the version tree and seeing exactly what was released. Part of the problem for me, I think, is that Onshape gives me a very "document-centric" perspective, which is perhaps good for design workflow, but not so good for review, inspection, and design-control workflows. The only way of getting to the release candidate information (that I can think of) is by first finding the right document and opening its version tree. 

Agree! we need a Release Management or Workflow page (tab) next to Documents and Activity. I can only think of our user/approvers/management that are part of our workflow, if they would have to navigate Documents the same way Designers do our implementation would get a lot of kick-back.

PeteYodis

I think what several people here are espousing is a way of seeing your data without needing to navigate a maze of documents and versions within documents.  IF we could offer that, would you still have issues with the version mechanism?  I suspect this topic is largely about the ability to easily consume data across all documents.  

tim_hess427

@PeteYodis - That's correct for me. Better visibility to the location, structure, and history of the data is what I'm after. And yes, with the improved visibility, the version and revision mechanisms would feel more natural. 

michael_bromley

@pete_yodis I would agree as well.  It seems another tool is needed instead of trying to make versioning something it is not.

brucebartlett

@PeteYodis this is exactly what is needed! A visual way to navigate the project or product outside of the documents, ideally based on the assembly structure with ability to clearly show components at the latest release and also link in other data like dxf's, spec sheets ,  pdf's. 

BulletEngineering

@pete_yodis - The version mechanism is, in my opinion, the killer app in OnShape. As @michael_bromley and @brucebartlett have noted, versioning is not an effective navigation or browsing tool. It is, however, indispensable for a multi-user design team. Have an idea? Snap a version, make a branch, and try it out. No messing with the parts someone else is painstakingly constructing into an exploded view, or removing geometry that was referenced for a mate. If it works and the team likes it, merge it in to main and snap a version to remember the event. 

When care is taken with version naming and notes, and combined with tab/part properties, it can be used as a crude 'released for production' packaging tool while while we wait for the dev team to make the new method to find our data Pete hinted toward. It's definitely a kludge, but better than not having a way to clearly indicate 'live' production data in a browsable fashion.

Michael_Coffee

When it comes to design work, having multiple part studios and assemblies in a document is useful in the sense that when a change it needed during development, it's instantaneous without any need for a new version. In my mind, if you want a proper release structure once the design of the part or assembly is complete, it requires moving it into its own document. My company groups the model and drawing into the same document. The exception would be with configured studios where they are instead separate and follow their own version management.

To me, the concept of keeping them all together within the same document is counter productive once you begin to implement any release management. Releases are tied to versions, but once you tie them to multiple versions in the same document, it will become a nightmare and leads to this problem of having to navigate the document history to exactly where and if something was released. Just my two cents, but it defeats the very purpose of release management within Onshape.

Having an interface to "look" inside of a document to at least see what its tabs are does sound like a good idea, but ultimately, how useful would it really be? One of our philosophies is "Keep it simple" and so each document would contain only as much as required, such as the model, its drawing, maybe a PDF, a table of technical data, but not much else. At max, maybe ten tabs, and all of them would relate in some sense to the part number it is assigned. Any more and you will begin to lose some of the advantages Onshape was designed for. I forgot which support guy said it, but to paraphrase what they said: a document is not a project folder. You cannot use release management on a document with multiple parts and assemblies and not expect something to go wrong.

philip_thomas

^^^

adrian_vlzkz

Michael_Coffee said:

To me, the concept of keeping them all together within the same document is counter productive once you begin to implement any release management. Releases are tied to versions, but once you tie them to multiple versions in the same document, it will become a nightmare and leads to this problem of having to navigate the document history to exactly where and if something was released. Just my two cents, but it defeats the very purpose of release management within Onshape. 

Completely agree, and I believe most of us in discussions like this here at realizing that.

The problem I see is that most technical content (except the one produced by @philip_thomas )  including formal training from Onshape, promotes the idea of containing a project within a Document as the "normal" workflow. That is why it gets confusing to those of us trying to form Guidelines or implementing Onshape at a Multi-User, Multi-Project environment.

I would advocate that Philip's methodology gets more "air-time" from Onshape, specially for the content targeted at Enterprise customers.

owen_sparks

I'll throw in the counter perspective.  Related parts go in the same doc, the Version of which is Irrelevant.  Parts are Revisioned and added to other documents as such...

brucebartlett

Finding released drawings in a document is a big issue for me. I tend to have drawings released across multiple releases and there is no way to navigate through lastest released drawing in one spot. The tab manager nicely to shows releases with a  filter but is constrained to versions, a tab manager raised above versions with a released filter would be a good start. Search from the home screen is the only option and when something gets the wrong name or number finding it becomes impossible with no visually way to search and no link to drawings from parts or assemblies. Navigating drawings over a document with 100 releases is not ideal but keeping a single document for a project still works well for me. I am still also exporting released pdf's after the release to a dropbox or google drive folder for most projects as there is no way to easily share the direct Onshape data with those needing access.  

StephenG

Interesting comments, but the discussion has deviated from its original intent...

"I would like for someone at Onshape, who was party to the decision to do versioning at the document level, attempt to set me straight, convince me, that versioning at the document level is a superior versioning method."

The most germane response came from @BulletEngineering, likening OS versioning to what is commonly used in software development. He also provided a link to a recently published (Feb 8, 2019) Technical Briefing https://learn.onshape.com/learn/article/gitflow-version-management which is a must read. It does contain background that kind of explains how OS views the version/revision process. The author presents an interesting usage case/approach for the design/release process; an approach I would have never considered. 

Based the comments so far, I get the impression a lot of us are still trying to figure out how best to take advantage of Onshape data management to get the most value of of the product. Onshape's data management approach is unique in the industry and different enough that it requires a change to your existing design/release process. Trying to plug in Onshape into your current process, or relying on previous usage experience with another product is going to be a frustrating experience.

We all began with a somewhat basic understanding of the OS data management elements: Documents, Workspaces/Branches, Versions/Revisions, Element Tabs, Part Studios, and the later added Projects, Document Folders/Labels, Tab Folders, and Part/Assembly configurations capabilities. However, if you are anything like me if is up to you to figure out (through empirical means) the in and outs, strengths and quirks of OS data management. I have learned how inaccurate my initial basic understanding was and have adjusted, but I still lack the confidence of knowing what I am doing is optimal for my needs.    
              
In regards to versioning of documents versus individual elements, I am guessing the decision was driven by a product philosophy which stresses and facilitates concurrent design and collaboration; everything ready to see, or not, needs to be available to everyone approved to see, or change it at all times; versioning documents makes that easier to effect. 

I would like to close this forum post by having an Onshape employee complete the following statement.

Versioning a document is better than versioning individual elements of a document because ____________________. 

michael_bromley

I'm not an Onshape employee, but I believe I can answer that question..

"Better than" is incorrect as the two are irrelevant.  Versioning a document is just that, versioning all elements.  If you want more granular control you use the release management and  revision process.

Think of the situation where you could version one part studio, how would you manage branching? the collaboration and working in process would become extremely convoluted.  I think it would muddy the waters further honestly.

StephenG

Given my growing understanding of OS versioning, let me reword the question so OS might comment.

Why did OS choose to deviate from the classical approach to versioning, where individual components within a MCAD design are versioned, and adopt a versioning philosophy commonly used for software development?

Clearly, there must have been good reasons. I just would like to be accurately informed as to what the reason were.

I think I have finally come to grip with the fact that OS versioning is nothing like versioning I grew up with; they are different species. Classical versioning at the Element/Tab level is off the table because of multipart Part Studios.

I will just have to get accustomed to seeing "Newer version available" type messages even though the flagged item has not changed from the referenced version of it. And having partially completed work being prematurely pushed because it happens to be within the same document.