Versioning
Contents
2024 Integration
Versioning applies to immortal evolution of product ecologies, and we thus take versioning seriously - consistent with lifetime design and lifelong learning for creating a democratic society.
The intent is swarming at the 1000 person scale in 4 years, and 1M person scale in 5 years, for one week vacations. This would yield 60k hours and 60M hours of highly coordinated development. The value thus created would be $3M at an hourly rate and $5M at a weekly rate ($5k/week value generation) - and in the 1M case $3-5B - sufficient to solve significant problems such as opensourcing a significant fraction of the technosphere, solving regional resource conflicts, etc.
- Main product dev follows the Main Convention as below
- Critical Paths are a great study of past planning and progress, so that one can assess build time more realistically - gaining insight into actual production. To version critical paths - keep the same Google Slides document, and make a copy as soon as you make any changes - to make slip readily transparent and thus a teaching moment.
- Data Collection versioning - add data collection by product, according to the Main Convention. Keep adding to the specific project for your contribution. An embedded spreadsheet would work great as well.
Introduction
Versioning is part of OSE's Taxonomy. The taxonomy allows for a logical organization of all content on this Wiki. Pending understanding of the taxonomy and Module Based Design, an unlimited number of contributors could work in parallel towards OSE's goal of creating an Open Source Economy.
Versioning
Versioning practice at OSE follows the naming convention of naming the module under development followed by v for version and date. Example:
3D_Printer_v19.10
This refers to the 3D Printer, the version whose start build date was October of 2019.
Notes:
- Use a unique name for everything. For example, 3D Printer v19.10 - is not the same as 3D Printer v18.09.
- When a new version is created, add that version to the list at the Genealogies page.
- Use a version at every level - Machine, Module, or Submodule/Part. Note that these different levels of detail are all considered as modules when referring to the development process: you can be developing the final product at the machine level, at the module level, or sub/part level. Each of these modules should have a version.
- When developing at the Module level, include the full name that identifies the largest unit of organization: for example: use 3D Printer Extruder v19.10, not Extruder v19.10. Same for part - use the 3D Printer Extruder Nozzle v19.10, not Nozzle v19.10.
- Use official naming convention of modules from GVCS Modules List.
- In name, use capital letters for all first letters of words in the name. Thus, it's 3D Printer, not 3D printer.
- Use v in small letters, which is short for version
- Since we go through multiple prototypes over multiple years - start with the year in the version name.
- Use month for the month the projects was STARTED. Since documentation is realtime and you don't know when the version development will end - it makes sense to use the month started.
- If multiple versions are iterated in the same month, name the latter one with the DAY it was started, such as v19.10.22 (for starting on October 22)
Difficulty of Applying the Second Toyota Paradox - Practical Example of Seed Eco-Home 2, 3, and 4
The Theoretical Controversy in the next section focuses on naming. But that's solved easily by making a decision one way or the other. The answer as in all complex systems is: both! And it is human integrity and value-add that provides meaning.
But the really difficult part, from the practical perspective - is how to treat multiple versions of a product-in-development. The Second Toyota Paradox prevents simple selection of one branch as the 'main branch' - if multiple development paths are ongoing. A single development path is representative of a non-collaborative development effort: one goes into a corner with their branch - and comes back with results. In a collaborative approach, the developer entertains and tracks multiple development paths - in order to synthesize the best answer from a mashup of solutions (because multiple solution paths are being entertained).
In practice - the discipline required is to treat every single build as a fork. This goes back to the principle: Every Hardware Build is a Fork. Ie - to produce separate documentation for each build. As opposed to using folders that do not disambiguate between versions - even if versions are named correctly inside the folders. Or trying to document on the wiki without setting up a new instance of a Dev Template. We do not use such folders in OSE documentation - but instead create an indexical environment in the form of an instance of the Development Template. The difficulty is: keeping awareness of which build is being worked on. For example, consider the partial build of Seed Eco-Home 2 of 2021. As soon as 2022 rolled around, we already had a next iteration with substantive, build time-saving changes. So we immediately set up documentation (an instance of the Development Template) for the next iteration. Which turned out to be not Seed Eco-Home 3 - another partial prototype - but Seed Eco-Home 4. The discipline of documenting required clarity on where to put the documentation. The answer is simple, but it requires working explicitly on multiple documentation sets: putting the existing as-built documentation under version 2, and those things that would be built next under version 4 - which wasn't built yet - or adding more documentation with time to version 3. No shit, right? Except that when it comes down to practice, it takes context-switching ability to document in multiple versions. It's just harder.
In practice, I was doing CAD on v4, build documentation on v2, design docs on v2 or v4 - pictures under v2 and v3. It is not possible to work on one version - otherwise important documentation would be lost (the principle of Future Documentation Never Happens. This is all an example of documenting under the principle of the Second Toyota Paradox. This is while not even considering Intuitive vs Semantic versioning - discussed next.
Semantic vs Intuitive Versioning Controversy - Theoretical
Software people favor the dot number convention (Semantic Versioning) v1.0, v1.1, v1.1.1 etc. This can be used, but OSE favors the more transparent date-based notation - which includes a sense of project management for overall project completion according to the Critical Path and Product Ecology - involving the 2028 finish date. Knowing which versions are being worked at the same time provides immediate information (by virtue of version date in the name) on project activity for purposes of coordination with large parallel teams.
Semantic Versioning solves for a different thing in software. In software, you can get to examples like: version 1.0.0-x.7.z.92. In hardware, you have 100x the documentation requirement because hardware requires about 100x-1000x more data to keep track of. In summary: that is very hard or impossible. The Semantic Versioning system applies only to simple documentation, and a more complex form, where granular breakdown is not explicitly documented, but instead taken from former versions, is required in hardware. In summary: software can be documented rigorously. Hardware can also be, but because it's more complex - an upgraded versioning system must be implemented to allow human-machine cooperation. When humans are doing versioning, they may use more intinuitive (including taxonomic breakdown items such as BOM, Build Instructions, Software, etc). For each of these - semantic versioning can be used as well. But for overall organization, since humans provide the meaning (and It Has Been Proven That Machines Cannot Produce Meaning) - then it follows that Intuitive Versioning must be used to augment the incompleteness of organization which is provided by Semantic Versioning.
. For example, you will not catch an artifact such as, this student in Djibouti used to much grease on a bolt. Point: you don't document everything. So a system of a different nature is required for hardware, and that's what the OSE system, summarized in OSE Development Protocol, embodies.
We can use semantic versioning for OSE software. But it's not a good idea to use semantic versioning for OSE hardware.
This makes no sense in hardware, because it's impossible to implement! Note that OSE documentation is comprehensive for machines. All known information is stored under the Template:Dev (20 items), Template:Enterprise - and these are the short versions for a total of 40 items in the short version and 100 overall. For each version, you have to keep track of 100 items, not just 1 like in software. So to have 100 pages for 1.0.0-x.7.z.92 is impossible. So what we do, is we make some documentation implicit. For example, if something is undocumented, one can check former versions in the Genealogy to see what came before.
To super-summarize: the problem statements are different in hardware and software because of the fundamental nature of the difference. Hardware has no uniform compiler! If you can understand this point, then I believe that the call for solely semantic versioning of hardware goes away. Bofem! Put in another way - Semantic Versioning solves for dependency hell. In hardware, each build is a new creation, and therefore, the concept of dependency hell does not arise because each build 'selects one dependency for each part'! So put in another way: OSE says yes to semantic versioning only if there were no real builds! -MJ.
