**Content** [TOC] --- # MDR-Linking ```mermaid flowchart TD OSII --- OSII_QMS OSII --- OSII_Scanners OSII_Scanners --- OSII_ONE OSII --- Magnets Magnets --- 30cm-Halbach-Magnet OSII_QMS --- MDR_magnet OSII_QMS --- MDR_OSII_ONE MDR_OSII_ONE -- refers to specific release of --> OSII_ONE OSII_ONE -- release links to specific version of --> MDR_OSII_ONE MDR_halbach-magnet -- refers to specific release of --> 30cm-Halbach-Magnet 30cm-Halbach-Magnet -- release links to specific version of --> MDR_halbach-magnet OSII_ONE -- links to specific release of --> 30cm-Halbach-Magnet ``` --- # Draft for the OSI² ONE Documentation Structure A graph to represent an assembly of OSI² ONE may look like this: ```mermaid flowchart TD Gradients_v1.0.2 --- OSII-ONE_v2.2.4 Magnet_v2.1.0 --- OSII-ONE_v2.2.4 Console_v1.1.1 --- OSII-ONE_v2.2.4 Console-Hardware_v1.0.1 --- Console_v1.1.1 Console-Software_v1.1.0 --- Console_v1.1.1 ... --- OSII-ONE_v2.2.4 ``` ## versioning ### general 1. everything that shall be versioned independently will be called a **module** - e.g. software and hardware for/of the console may want to be versioned independently (e.g. in the case of bug fixes) 1. every module has it's own repo - …so they are also developed in dedicated repos (e.g. "console-software", "console-hardware") 1. a connection between modules is an interface (e.g. ports, dimentions, power input) 1. interfaces may be described by an overarching specification in an own repo ("product model" for larger machines) or repo-specific e.g. in the README (to keep things simple) - if we introduce small metadata files (e.g. an INTERFACE file), we could "crawl" them and generate a product model (= the combination of all interfaces)… for whatever that's useful 1. a repo of a module may contains: - a bill of materials - parts - instructions - _version-specific_ references to other modules ### versioning scheme 1. every repo is versioned independently - using `git tags` and `releases` on GitLab - releases should include a changelog 2. building subassemblies (=versioning modules containing submodules) only makes sense, when the entity itself shall be independently versionable (e.g. the `console` containing independently developed modules) 3. versioning scheme: we use [Semantic Versioning v2.0.0](https://semver.org/) ### detail `MAJOR.MINOR.PATCH` - `MAJOR` version when you change an interface - e.g. static magnet has a (significantly) different size now - `MINOR` version when you add functionality in a backwards compatible manner - e.g. console comes with an extra slot now or is faster than the previous version - `PATCH` version when you make backwards compatible bug fixes - e.g. capacitor used to blow up after 200h of usage → replaced with a bigger one - when a version of a submodule changes, the versions of the affected superordinated modules change accordingly (Additional labels possible (e.g. `beta`) consequently: - all `MINOR` versions of the same `MAJOR` version are _theoretically_ backwards-compatible to each other; however not all setups may have been tested (e.g. when 2 submodules change at the same time and the setup is not tested individually) and there may also exist (untested) compatibility of parts across `MAJOR` versions - EXAMPLE: `Magnet_v2.1.0` should work as a replacement of `Magnet_v2.0.0`, meaning that any setup is _theoretically_ upgradebale – however only specific combinations of versions of submodules have been tested and deployed. It may be that `Magnet_v2.1.0` comes with properties that could be utilized with `Console_v1.1.1`, but my old `Console_v1.0.4` doesn't support that feature of the magnet since it hadn't been invented at that time ### branch management - branch per major version (e.g. `v1`) - so that later updates of previous verions do not interfere with later versions - major version branch is only updated via merge requests from feature branches (e.g. `new-material-for-lids` merged into `v1`) ```mermaid gitGraph commit commit branch develop checkout develop commit commit checkout main merge develop commit commit ``` ### IRL - every physical reprentation of a module or part must be referenced to its documentation - modules/parts in automotive settings have unambiguous model numbers - this can be done using QR codes or permalinks or other identifiers - using laser engravement, stickers etc. - BUT when the setup is upgraded locally, these references need to change accordingly (e.g. by putting new stickers over the old ones) <!--- #### branch management We'll have 3 kinds of branches: - `main` (= stable releases) - `dev` (= the place where a new version is developed) - temporary feature branches (that merge into `dev`) All changes are done on a new feature branch. If these changes get approved, they'll be referenced in the changelog of the next release --> ## compatibility A module version is always just a (stable) snapshot of the ongoing development. The current version of a larger module/assembly may not contain the latest versions of all submodules. There will be loads of combinations of module versions for the final assembly – too many to officially support them all (or even to provide upgrade documentation for all) Module combinations can be: - a) officially supported (active) - b) formerly officially supported (deprecated) - c) community-approved - d) unknown a) & b) are documented in the release history of the overarching assembly repo (by BOMs). c) is documented in community forks (by BOMs)