Merge Workflow

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.

Links

• Open Source Hardware Taxonomy
• OSE Open Source Hardware Taxonomy