Merge Workflow

From Open Source Ecology
Jump to: navigation, search


Merge Workflow is a technique where, without locking down design files, collaboration can occur on a single CAD design with an unlimited number of people. The workflow relies on merging parts into working documents in positionally-correct locations. To address the issue or correct part location, part placeholders are started in an assembly document - in a positionally correct location. These parts can subsequently be edited in separate documents. Source files are uploaded on an ongoing basis. For onboarding of additional designers, uplaods incude Visual Version History, and live-editable Working Docs support the design process. Because nothing is locked down and ongoing communication between developers occurs via video in realtime or via work docs asynchronously, this process can leverage the input of large teams, using common off-the-shelf software, FreeCAD.


HintLightbulb.png Hint: This is one of core OSE collaborative, open development protocols. You are welcome to improve this page by editing mercilessly.

The key to successful management of large scale, global, open development collaboration - hardware or software - is Modular Breakdown of complex projects into small parts.

For the case of hardware designs - modular breakdown means that we break machines and product systems down to their smallest components.

Tracking any development effectively, and collaborating on a large scale - requires that each component is distinguished from the overall product - such that it can be developed independently and in parallel with many other components.

Scalable parallel development can exist on the level of an overall product, its module, and its sub-modules or components.

To document products and components, we use Part Libraries. Part libraries are also convenient in terms of how they can be modified using FreeCAD. A developer or user should be able to download parts and overall products from part libraries. To understand how part libraries relate to FreeCAD and large-scale parallel development - we must understand the Merge Workflow in FreeCAD:

  1. FreeCAD has a Merge Workflow option. Go to File->Merge project... to access this workflow.
  2. Proper use of this workflow allows files on the wiki - parts - to be merged into the same document.
  3. To use this workflow - files must be saved in a positionally correct location. This means, that when a second part it merged with a first part - it appears in a location like in the final product.
  4. One can start by downloading any single part, and merge new parts into the same working document as needed
  5. This way of handling parts allows full modular breakdown. Each file or part is accessible.
  6. Anyone can work on any part, and uplaod changes to the wiki on a granular basis.
  7. The wiki keeps old versions, so that we can work with older versions if needed at any time. The wiki thus has a full ability to do version history. It is useful to annotate older versions (either in file comments or on the wiki page for the versioned file) so other developers can see what the version contains.
  8. The main point of this is allowing many people to work in parallel on the same CAD design.
  9. Another advantage is retaining full versioning control on parts, not only on overall assembly.
  10. Another advantage is file size management: instead of uploading complete files, it takes much less disk space to upload only the changing parts. This becomes increasingly important with growing project size/complexity.

The above summarizes how to work using the Merge Workflow. This can be used in conjuntion with more advanced workflows such as using the Asembly 2 Workbench.

More Notes on the Merge Workflow

  1. It is useful to include a Visual Version History in the part library - which simply means pictures of snapshots of the file as it evolves in time. New snapshots are included for visual reference - to save time in assessing the content of files. This is an antidote to Git or other drop-box like platform - where a wall of filenames of parts takes time to parse for content. Git does not allow versioning at a granular level (new uploads over an existing individual files), only at a repository level. This does not work well for open hardware development because 2 component CAD files cannot be compared side by side.
  2. For solo work, it's acceptable to use git or other 'whole project versioning'
  3. Note that 'whole project versioning' at the level of CAD does not work well for large, collaborative open hardware, as CAD and software are only a small portion of an overall project. Thus, a wiki is still required to manage many other data formats while allowing for powerful organizational, taxonomy, or semantic organization aspects.
  4. The power of a wiki is the reason why OSE uses the wiki-based Development Template, which is cloned in full for the next iteration. Parts of the Development Template are updated as needed, while keeping the whole project version intact.


This example applies to using FreeCAD workflows to design a large and complex project with a large number of people (1000 or so) working in a Window of Opportunity framework - in a short, 1 day period. This is an expected scenario that OSE is working on - through its STEAM Camps program, Summer of Extreme Design-Build, Extreme Manufacturing Workshops, and Incentive Challenges.

The two options are using the Merge Workflow vs Assembly Workbench workflow.

Take an example of 1000 people design a rocket ship in one day by splitting the project into 1000 parts, by defining interfaces, and saving the files in positionally correct locations defined by the interfaces. This allows realtime, rapid development that is not possible in a FreeCAD assembly workbench workflow, because only one person can work on an assembly without running into merge conflicts. The most granular development method is thus afforded more effectively using the merge workflow.