Improving Versioning
Summary
- proposal to address issues with consistent versions of machines
- OSE's core business is actually producing documentation for machines available over a lifetime
- Good about the current situation
- proven technology, easy-to-use centralized wiki
- easy to use Google Presentations cloud application for build manuals
- Problems with the current situation
- wiki unstructured and overwhelming
- no real versioning in wiki and Google Presentations
- reliance on volatile, proprietary Google cloud services
- binary format for Google Presentations prevents proper versioning
- Requirements
- no major change in current workflow
- keep the wiki as central point
- do not rely on the wiki as a central point
- apply proper versioning reflecting severity of change
- true consolidation of machines with lifetime releases
- versioning supporting modularity
- no reliance on proprietary software/cloud services
- support textual format as much as possible for universal versioning
- same ease-of-use as Google Presentations
- automatic index for machines, modules, projects on the wiki
- Proposal
- adopt semantic versioning
- adopt Git with submodules
- create lifetime releases with Zenodo or IPFS
- automatically generate wiki pages, build manuals from Git repositories
- find a way to use a textual format as an easy-to-use replacement for Google Presentations
- Concrete steps
- Investigate the above in the Hamburg STEAM Camp
Introduction
Several projects in OSE become viable products, for example the D3D Universal and D3D Pro are being sold as kits. However, the nature of OSE is that many projects are in a high rate of development and versions may change much in a short amount of time. For example, the D3D Universal changed considerably from the summer of 2019 to January 2020 and possibly as a result the documentation on the wiki was not consistent.
On this page we will try to address some the issues. We will first elaborate on the context, then we will discuss what is good in the current situation. We will then define the problem and finally outline a set of ideas and requirement to improve on the status quo.
Context
Many machines are reaching a state that makes them a viable product. For others to be able to use them, we need proper documentation that is consistent over versions. The machines are highly modular which means that some version of machine A uses some version of project B. If B advances, it may no longer be a fit to A. As such, it is necessary to maintain bookkeeping about which version of a different component is used.
We could ask ourselves what OSE's core business is. An acceptable answer would be producing the machines of the GVCS. However, a more refined answer would be that OSE produces documentation to build the machines of the GVCS. To be able to repair them, it is necessary to understand it, hence the documentation.
An interesting feature of the OSE machines is that they should be usable over a lifetime. However, this would also require for the documentation to be available over a lifetime. It is not clear whether that is guaranteed currently.
Another question is then: What does it mean that the machine is available over a lifetime? Is the machine (rather its documentation) built now available in 20 years? Is the documentation of that specific version available? The machines built now are versioned using year and month. Or is only the current documentation available of the machine in the current state?
Qualities of the current situation
The current system in place has various good features. The OSE wiki has pages for each project where information and build manuals are stored. A wiki is proven method with a low entrance threshold for users. The wiki logs changes to the pages and people making the changes. Major benefits are:
- one central point of entry
- anyone can join
- ease of use
- logs activity with changes
- proven technology
Many of the build manuals are created in Google Presentations. This is a highly easy-to-use cloud application. Anyone can view the presentation and download it in various formats such as Microsoft Powerpoint, Libre Office, or PDF. It also supports templates to provide a fixed style and the application keeps track of versions although these versions are not available to the public as opposed to the wiki pages.