Improving Versioning - Revision history

Marcin at 17:31, 23 June 2020

2020-06-23T17:31:57Z

← Older revision		Revision as of 17:31, 23 June 2020
Line 1:		Line 1:
			Read source about Semantic Versioning - https://semver.org/

	== Summary ==		= Summary =

	* proposal to address issues with consistent versions of machines		* proposal to address issues with consistent versions of machines

Marcin: /* 3) Do not rely on the wiki as a central point */

2020-06-23T17:22:37Z

3) Do not rely on the wiki as a central point

← Older revision		Revision as of 17:22, 23 June 2020
Line 86:		Line 86:
	Can we download, and backup ALL of the wiki or parts, like one can with wikipedia? Magnetic Tape Cartriges, or archival optical disks are cheap/tb and can last for a long time, two of thos physical in seperate places, and a cloud, and we should be good? (plus frequent backups). Also any way to trigger a wayback machine "copy" ?		Can we download, and backup ALL of the wiki or parts, like one can with wikipedia? Magnetic Tape Cartriges, or archival optical disks are cheap/tb and can last for a long time, two of thos physical in seperate places, and a cloud, and we should be good? (plus frequent backups). Also any way to trigger a wayback machine "copy" ?

	{{Hint\|The wiki is currently backed up daily, weekly, monthly, and yearly on Backblaze. Failure requires both the server with its RAID-1 backup, and the Backblaze backups, to be destroyed simultaneously. OSE is also available for off-line viewing, ~~see~~		{{Hint\|The wiki is currently backed up daily, weekly, monthly, and yearly on [[Backblaze]]. Failure requires both the server with its RAID-1 backup, and the Backblaze backups, to be destroyed simultaneously. OSE is also available for off-line viewing, so there is a distributed download available from users who have done this. See more at https://www.opensourceecology.org/offline-wiki-zim-kiwix/. Currently, the entire wiki is 2.8 GB.}}

	=== 4) Apply proper versioning ===		=== 4) Apply proper versioning ===

Marcin: /* 3) Do not rely on the wiki as a central point */

2020-06-23T17:19:55Z

3) Do not rely on the wiki as a central point

← Older revision		Revision as of 17:19, 23 June 2020
Line 85:		Line 85:

	Can we download, and backup ALL of the wiki or parts, like one can with wikipedia? Magnetic Tape Cartriges, or archival optical disks are cheap/tb and can last for a long time, two of thos physical in seperate places, and a cloud, and we should be good? (plus frequent backups). Also any way to trigger a wayback machine "copy" ?		Can we download, and backup ALL of the wiki or parts, like one can with wikipedia? Magnetic Tape Cartriges, or archival optical disks are cheap/tb and can last for a long time, two of thos physical in seperate places, and a cloud, and we should be good? (plus frequent backups). Also any way to trigger a wayback machine "copy" ?

			{{Hint\|The wiki is currently backed up daily, weekly, monthly, and yearly on Backblaze. Failure requires both the server with its RAID-1 backup, and the Backblaze backups, to be destroyed simultaneously. OSE is also available for off-line viewing, see

	=== 4) Apply proper versioning ===		=== 4) Apply proper versioning ===

Pieter: Pieter moved page Semantic Versioning to Improving Versioning: The title "Semantic Versioning" is too specific for the proposal.

2020-05-25T17:08:43Z

Pieter moved page Semantic Versioning to Improving Versioning: The title "Semantic Versioning" is too specific for the proposal.

← Older revision	Revision as of 17:08, 25 May 2020
(No difference)

Pieter: /* 3) Do not rely on the wiki as a central point */

2020-05-25T15:56:31Z

3) Do not rely on the wiki as a central point

← Older revision		Revision as of 15:56, 25 May 2020
Line 83:		Line 83:
	=== 3) Do not rely on the wiki as a central point ===		=== 3) Do not rely on the wiki as a central point ===
	The danger of a central point is that if the wiki goes offline, lots of very interesting information, a legacy, will be lost. It may be possible to protect for this.		The danger of a central point is that if the wiki goes offline, lots of very interesting information, a legacy, will be lost. It may be possible to protect for this.
	~~'''~~Can we download, and backup ALL of the wiki or parts, like one can with wikipedia? Magnetic Tape Cartriges, or archival optical disks are cheap/tb and can last for a long time, two of thos physical in seperate places, and a cloud, and we should be good? (plus frequent backups). Also any way to trigger a wayback machine "copy" ? ~~'''~~
			Can we download, and backup ALL of the wiki or parts, like one can with wikipedia? Magnetic Tape Cartriges, or archival optical disks are cheap/tb and can last for a long time, two of thos physical in seperate places, and a cloud, and we should be good? (plus frequent backups). Also any way to trigger a wayback machine "copy" ?

	=== 4) Apply proper versioning ===		=== 4) Apply proper versioning ===

Pieter: /* Problem definition */

2020-05-25T15:51:10Z

Problem definition

← Older revision		Revision as of 15:51, 25 May 2020
Line 62:		Line 62:
	Although there are certainly good things to say about the current situation, unfortunately it is also possible to name deficiencies. One of the problems of the wiki is that it contains lots of information in a more or less unstructered way. Navigation is reliant on links between pages, there is machine information, firmwares, "meta" topics such as this, etc. A common complaint is that users find it hard to find their way and get overwhelmed with the content.		Although there are certainly good things to say about the current situation, unfortunately it is also possible to name deficiencies. One of the problems of the wiki is that it contains lots of information in a more or less unstructered way. Navigation is reliant on links between pages, there is machine information, firmwares, "meta" topics such as this, etc. A common complaint is that users find it hard to find their way and get overwhelmed with the content.

	Although a wiki keeps track of changes, it is on a per-page basis and not really meant for versioning. (It is rather a mechanism to make and compare snap-shots.) To the best of my knowledge, it is not impossible to mark a page as being in a state that should be consolidated, for a machine release for example.		Although a wiki keeps track of changes, it is on a per-page basis and not really meant for versioning. (It is rather a mechanism to make and compare snap-shots.) To the best of my knowledge, it is not impossible to mark a page as being in a state that should be consolidated, for a machine release for example. Furthermore, there is no mechanism to add in-place comments (and comment on comments), which seems desirable for a collaborative workflow and resolving merge conflicts in the wiki is not intuitive.

	Furthermore, there is no mechanism to add in-place comments (and comment on comments), which seems desirable for a collaborative workflow.

	~~Resolving~~ merge conflicts in the wiki is not intuitive ~~and seems a nightmare!!~~

	A problem with the way machines are versioned is that the version number does not reflect how severe a change is. Does a minor change lead to a new version number, for example a new Z-sensor on a 3D-printer? Perhaps it does, it may get version 20.04, but if next month the layout of the axes change, it may get version 20.05, whereas it is a major change. And 3D-printer 20.05 may make use of an improved universal axes but which version? Do we consistently change the 3D-printer version if the universal axis version number changes? Managing these version numbers requires lots of discipline in the current situation.		A problem with the way machines are versioned is that the version number does not reflect how severe a change is. Does a minor change lead to a new version number, for example a new Z-sensor on a 3D-printer? Perhaps it does, it may get version 20.04, but if next month the layout of the axes change, it may get version 20.05, whereas it is a major change. And 3D-printer 20.05 may make use of an improved universal axes but which version? Do we consistently change the 3D-printer version if the universal axis version number changes? Managing these version numbers requires lots of discipline in the current situation.
Line 72:		Line 68:
	The build manuals are drafted in Google Presentations but this has drawbacks. Firstly, editing requires a Google account. Secondly, the application is a proprietary cloud application from a major company that has so many resources that they can build an extremely high quality cloud application. However, this results in high degree of [https://en.wikipedia.org/wiki/Vendor_lock-in vendor lock-in]. Google cloud services are highly volatile, see the [https://en.wikipedia.org/wiki/Google_Reader#Discontinuation discontinuation of Google Reader], [https://en.wikipedia.org/wiki/Google%2B Google +], and the number of video conferencing applications that may or may not be merged: Google Meet, Google DUO, Google Hangouts, Google chat, and all of these may or may not be integrated with Gmail. The point is that being reliant on such a large, volatile company where services may be canceled, terms of service may change is not a very "open" way of working.		The build manuals are drafted in Google Presentations but this has drawbacks. Firstly, editing requires a Google account. Secondly, the application is a proprietary cloud application from a major company that has so many resources that they can build an extremely high quality cloud application. However, this results in high degree of [https://en.wikipedia.org/wiki/Vendor_lock-in vendor lock-in]. Google cloud services are highly volatile, see the [https://en.wikipedia.org/wiki/Google_Reader#Discontinuation discontinuation of Google Reader], [https://en.wikipedia.org/wiki/Google%2B Google +], and the number of video conferencing applications that may or may not be merged: Google Meet, Google DUO, Google Hangouts, Google chat, and all of these may or may not be integrated with Gmail. The point is that being reliant on such a large, volatile company where services may be canceled, terms of service may change is not a very "open" way of working.

	~~More generally speaking, it may be useful~~ to ~~evaluate~~ what degree of vendor lock-in in still acceptable. For example, using GitHub may be acceptable if the repository is mirrored in some form. GitHub's issue tracker may be leveraged because it gives out-of-the-box, user-friendly functionality, but with the understanding that it may go away any time (e.g., because of DMCA take-down.)		It is debatable to what degree vendor lock-in is still acceptable as there are also examples without much reliance on a particular cloud service. For example, using GitHub may be acceptable if the repository is mirrored in some form. GitHub's issue tracker may be leveraged because it gives out-of-the-box, user-friendly functionality, but with the understanding that it may go away any time (e.g., because of DMCA take-down.)

	More practical issues are the following: The internal format is not exposed to the user. The format is binary instead of textual which makes tracking changes more cumbersome and reliant on the used application.		More practical issues are the following: The internal format is not exposed to the user. The format is binary instead of textual which makes tracking changes more cumbersome and reliant on the used application.

Pieter: /* Qualities of the current situation */

2020-05-25T15:45:53Z

Qualities of the current situation

← Older revision		Revision as of 15:45, 25 May 2020
Line 53:		Line 53:
	* logs activity with changes		* logs activity with changes
	* proven technology		* proven technology

	Arguably, the wiki's ease of use is relative and highly depends on the user's prior experience with editing wikis. For example, since editing and viewing the rendered results requires extra clicks, the workflow is not ideal. Embedding of external resources is brittle and requires copy-and-pasting of HTML-snippets (and the rendering of these external links depends on the browser's privacy settings).

	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.		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.

	Google Presentations are indeed easy-to-use, ~~but can also be a challenge because~~ keeping formatting consistent can be ~~frustrating~~ and time-consuming.		Although we list qualities here, these qualities are debatable. For example, the wiki's ease of use is relative and highly depends on the user's prior experience with editing wikis. For example, since editing and viewing the rendered results requires extra clicks, the workflow is not ideal. Embedding of external resources is brittle and requires copy-and-pasting of HTML-snippets (and the rendering of these external links depends on the browser's privacy settings).
			In addition, although Google Presentations are indeed easy-to-use, keeping formatting consistent can be challenging and time-consuming.

	== Problem definition ==		== Problem definition ==

Kienle: /* Semantic versioning */

2020-04-21T09:42:47Z

Semantic versioning

← Older revision		Revision as of 09:42, 21 April 2020
Line 118:		Line 118:

	This scheme is most dominant in software engineering and it may be wise to learn from it and adopt it. This would satisfy requirement 4.		This scheme is most dominant in software engineering and it may be wise to learn from it and adopt it. This would satisfy requirement 4.

			In addition to semantic versioning, which is linear, we also have to think about accommodating "alternatives/options/configurations". For example, the "same" printer has different components for power supply depending on the region (e.g., US has a US-plug and GFCI, most of Europe has a Europlug, etc.). Printer versions have gone back and forth between 2-pin/3-pin endstops, but it may make sense to have both configurations as user-selectable option (and depending on the choice a matching firmware configuration is needed).

	=== Distributed versioning systems ===		=== Distributed versioning systems ===

Eric: Added some more information

2020-04-20T17:36:58Z

Added some more information

← Older revision		Revision as of 17:36, 20 April 2020
Line 88:		Line 88:
	=== 3) Do not rely on the wiki as a central point ===		=== 3) Do not rely on the wiki as a central point ===
	The danger of a central point is that if the wiki goes offline, lots of very interesting information, a legacy, will be lost. It may be possible to protect for this.		The danger of a central point is that if the wiki goes offline, lots of very interesting information, a legacy, will be lost. It may be possible to protect for this.
			'''Can we download, and backup ALL of the wiki or parts, like one can with wikipedia? Magnetic Tape Cartriges, or archival optical disks are cheap/tb and can last for a long time, two of thos physical in seperate places, and a cloud, and we should be good? (plus frequent backups). Also any way to trigger a wayback machine "copy" ? '''

	=== 4) Apply proper versioning ===		=== 4) Apply proper versioning ===
Line 157:		Line 158:
	== Concrete Steps ==		== Concrete Steps ==
	A proposal is to investigate all of this as part of the STEAM Camp Hamburg. A good use case is to apply the above methodology to the D3D-Univeral. After this experiment, we can evaluate this methodology compared to the current workflow.		A proposal is to investigate all of this as part of the STEAM Camp Hamburg. A good use case is to apply the above methodology to the D3D-Univeral. After this experiment, we can evaluate this methodology compared to the current workflow.

			=See Also=
			*

			=Useful Links=
			*[https://www.youtube.com/watch?v=gShRBsahzXg A Youtube Video on USB's Recent Failure at Naming Standards Reflecting Change, and Making Sense]

Kienle at 14:51, 20 April 2020

2020-04-20T14:51:06Z

← Older revision		Revision as of 14:51, 20 April 2020
Line 139:		Line 139:
	As the benefit of the wiki is clear, we need some way of bringing all of the above together. A proposal is to move serious development of the machines to a dedicated Git repository, for example 'univeral-axis' and 'd3d-universal'. The Git repositories contain a LICENSE file, a README, a CONTRIBUTING, a Changelog file, a VERSION file, and a Makefile, just as in a open-source software project. The README explains how the repository works, for what machine the repository is, etc. The CONTRIBUTING file defines a set of guidelines to aid users in contributing content. The Makefile is essentially a script that keeps track of dependencies between files and 'builds' the project, we will come back to this later. The other files are self-explanatory.		As the benefit of the wiki is clear, we need some way of bringing all of the above together. A proposal is to move serious development of the machines to a dedicated Git repository, for example 'univeral-axis' and 'd3d-universal'. The Git repositories contain a LICENSE file, a README, a CONTRIBUTING, a Changelog file, a VERSION file, and a Makefile, just as in a open-source software project. The README explains how the repository works, for what machine the repository is, etc. The CONTRIBUTING file defines a set of guidelines to aid users in contributing content. The Makefile is essentially a script that keeps track of dependencies between files and 'builds' the project, we will come back to this later. The other files are self-explanatory.

	The main content of the repository consists of documentation in textual format together with the CAD files of the project. With all this content we can 'build' the project which means in this situation that we generate documents for the machines. An example would be to 'make' the build manual or 'make' the wiki page of the project, or 'make' the BOM. The make script would ideally automatically generate images from the CAD files to be used in the documents that this project generates.		The main content of the repository consists of documentation in textual format together with the CAD files of the project. With all this content we can 'build' the project which means in this situation that we generate documents for the machines. An example would be to 'make' the build manual or 'make' the wiki page of the project, or 'make' the BOM. The make script would ideally automatically generate images from the CAD files to be used in the documents that this project generates. (This seems feasible for FreeCAD [[https://wiki.freecadweb.org/Std_ViewScreenShot]], since it can be scripted and run headless.)

	As such, we can generate a wiki page and add that to the wiki ensuring that the information on the wiki remains consistent. We could also automatically create an index for the wiki for several of these project, satisfying requirement 10.		As such, we can generate a wiki page and add that to the wiki ensuring that the information on the wiki remains consistent. We could also automatically create an index for the wiki for several of these project, satisfying requirement 10.