changed 2 years ago  
Published Linked with GitHub

Versioning and Releasing Open Hardware content

Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →
Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →

Date of release: 16-09-2022

Is publishing content openly enough to call it an open source release? Not all open content has the same quality, relevance, adoption, and implementation of requirements that comply with open source practices and standards. How is content released in projects that involve the active participation of many contributors and users? In this lesson we aim to cover what a release is in a broader and technical sense. We will cover what is the relationship between versioning and releasing to communicate important aspects of the lifecycle of an open source project.

By the end of this lesson you should be able to

  • Plan and execute a release of open hardware content
  • Use versioning in your releases

Learning objectives

  • Understand the role of releasing in open source development
  • Go through essential steps of releasing open hardware content
  • Implement open hardware principles using releases
  • Apply versioning to communicate the status and developments of your project

Introduction

As found in the first lesson of the Open Hardware Academy, the definition of open source hardware is: "hardware whose design is made publicly available so that anyone can study, modify, distribute, make, and sell the design or hardware based on that design." Read more on the OSHWA definition of open source hardware. This lesson focuses on the activities associated to the distribution of open hardware design documents/data.

Some useful definitions and ideas

Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →
Many concepts and definitions in open hardware are derived and adapted from the open source software domain. In this section, we take explanations and references found in software which we feel are also relevant and applicable to hardware design.

Release:

  • Definition: A product release is the process of launching a new product for a specific market or user base. In software development, a product release is sometimes done with a beta version so that core developers/users can assist with debugging and feedback prior to the release of the actual software. from techopedia
  • Releasing falls within distribution and product delivery activities
  • There is a key difference between releasing a product/project and publishing content.
  • Releasing (as normally referred to in the industry) involves the publication of content but it also involves much more than that.
  • This includes other activities such as communication, community engagement, proper versioning, release notes, the development of complementary material like tutorials, and extended documentation, up to campaigns of all kinds from crowdfunding to marketing campaigns.

Versioning:

  • Definition: Versioning is the process of numbering different releases of a particular product or component for both internal use and release designation. It allows developers to know when changes have been made. At the same time, it enables potential customers/users/contributors to be acquainted with new releases and recognize the updated versions.Modified definition from techopedia
  • Image Not Showing Possible Reasons
    • The image file may be corrupted
    • The server hosting the image is unavailable
    • The image path is incorrect
    • The image format is not supported
    Learn More →
    In this lesson, we cover only the aspect of versioning focused on communicating the status of a project, .i.e version 0.1.0, or version 1.1.0 . This labeling convention of content with numbers helps to provide context on wether a project is undergoing major changes,  if a new release has patched a bug found, or if a new feature has been implemented. Conventions in semantic versioning allow for communication between these and other aspects. For example when a new idea/prototype is being developed this is often labeled as v0.1.0.
  • A design can have many lives and derive into new designs, each of which has its own specifications and complementary documentation often delivered as releases. The following images show a small portion of RepRap versions.


A small portion of a version tree of RepRap printers retrieved from link

Semantic versioning conventions for software that has applicability for hardware

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes
  • MINOR version when you add functionality in a backward-compatible manner
  • PATCH version when you make backward-compatible bug fixes

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Release channels: This is an important aspect of releasing activities. Examples include Github, Wikifactory, Gitlab, Hackaday, Thingiverse, among many others. OSWHA has a list of interesting channels that include HardwareX, The Journal of Open Hardware and The Journal of Open Engineering.

Open source release management

Some characteristics of open source releases

In advanced projects releasing is only a milestone in the lifecycle of an open source project. In fact, it is a life cycle management activity. In this section we explain briefly key aspects that explain releasing as a complex project development activity:

  • In the context of advanced open source projects a release is a major event that communicates a milestone of a project to a broader audience and complies with a certain level of expectation by community members.
  • As part of a project's lifecycle management and helps teams and communities to work together towards shared goals.
  • It communicates a changelog communicating what new things have been added to the design.
  • It can be paired with other community engagement activities
  • They can be used to dialogue with the community to get feedback from users for example when a beta version is released, the label beta notifies that such a version is still unstable or in a testing period.

Alpha and Beta releases

Alpha and beta releases are very concrete examples of product/project lifecycle management that also incorporate versioning and audience engagement.

When a project is released as an alpha version it means that a major intent behind the release is to get feedback often referred to as "acceptance testing". Basically, it means that contributors/users are invited to help the developers to check if the requirements of the design are met.

Alpha and Beta Testing phases mainly focus on discovering the bugs from an already tested product and they give a clear picture of how the product is used by the real-time users. They also help in gaining experience with the product before its launch and valuable feedback is effectively implemented to increase the usability of the product.

Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →
Read more about alpha and beta testing.

Getting started

In the context of open source projects, there are clear definitions, practices, and standards that constrain or specify an open source release. These requirements can be found in the OSHWA declaration of principles as well as definitions. These requirements, therefore, set some minimum deliverables for open source projects which includes the documentation, licensing and publishing of the design to be released.

Planning an open source release

Think of it as an activity within the lifecycle management of your project where you try to match your expectations and goals, with the final deliverables of your project. In our context, a release needs to contain all the information needed to reproduce and rebuild a hardware design (this is independent of whether is an experiment, a hack, a prototype, or a fully featured product). This is what constitutes a unit of work or useful outcome that can be used to build upon.

Tips and examples

  • You can think of your release as the final step of delivering the outcome that matches the expectations, framing, and original motivation and planning of your itteration.
  • A release can also be the final step of a sprint where you focus on a feature or component that other developers and contributors can use to help you work on your project.
  • A release can be the start of the next phase of feedback from users and contributors.
  • A release can be a step in the validation plan of your product vision.
  • It can be also an important update on your product/project still in development.
  • A release in open hardware DIY context can also be the documentation of a hack or an experiment often found on platforms such as hackaday or openbuilds.

Tools and methods to plan your release

Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →
The following list of tools have quite some overlap with our previous documentation lesson. This is because design documentation is the most important component of a release.

Tools & Methods Comments and observations
Open Hardware Canvas This canvas provides a very useful checklist of common aspects you need to look after in open hardware projects. It can be the basis for planning a release and capturing essential aspects of it
Open Hardware Certification OSHWA Certification provides an easy and straightforward way for producers to indicate that their products meet a uniform and well-defined standard for open-source compliance.
DIN Spec 3105 It delivers an unambiguous and operational definition of the concept of open source hardware and breaks it down into objective criteria for judging the compliance of a piece of hardware with this definition…Read more
Semantic versioning A naming convention for data packages/repositories that provides information about a project's history and status
Release management with github This is a specific feature within GitHub that allows you to have a log of releases next to release notes as well as complementary data and files that can be downloaded.
Documentation standards provided by Open Hardware Observatory This can also be used as a checklist to make sure you comply with OHO recommendations.
Standardized open hardware metadata generator provided by open know-how This metadata standard allows adding a manifest file next to your hardware project that can help in making it more discoverable in specific open hardware-focused channels.
Release-oriented events Events help you showcase and tell a complete story of your project including your vision, ambitions, call for help, etc. This can also include a set of activities such as replication workshops
A project kanban board with tasks and milestones There are many tools available to visualize the status of your project provided by widely used channels and development platforms such as GitHub, GitLab, but also Trello, to name a few examples.

Exercises

Exercise 1: Define what kind of release you are working towards

Instructions:

  • Specify what is the scope of your content to be released
  • Consider this scoping for the next section on planning a release.
Scope
An experiment/hack/build
An alpha prototype meant to get feedback from early adopters
A beta prototype to get feedback from the public
A fully maintained and supported open hardware project
Lifecycle and continuity
Project is a one-time release
Project is being maintained and in continuous development
Project is seeking user feedback
Project is looking for contributors

Exercise 2: Make a release checklist that you can easily incorporate as tasks in a project board

Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →
This template is based on the [open hardware canvas provided by open makers](https://curriculum.openhardware.space/articles/01-welcome-to-ohm/canvas/)

Instructions

  • Fill in the template fields with checkpoints, todos, and considerations to make your release plan and notes more clear.
  • If you have a project board or you are using issues consider adding the different tasks to your board
  • If you are approaching your project progressively you can design a release sprint where you add these tasks to your release sprint backlog.
  • Share your release planning notes to get feedback
# Release planning notes
## Release notes
- What is the status of the project?
- What features were implemented?
- Add your semantic versioning if applicable
-

## License(s) for different modules of the project
 - TODO 
...

## Bill of materials
...

## Assembly instructions
...

## Source files
...

## Resources and materials needed to re-use and or work in the project

## Contributor Channels
...

## Contributor Docs
...

## User channels
...

## User Docs
- Select documentation medium
- Your documentation package in a sharable format
...

## Similar projects (Optional)


## Metadata (added if applicable)

References

[1] “Open Hardware Makers Curriculum : Open Hardware Canvas.” https://curriculum.openhardware.space/articles/01-welcome-to-ohm/canvas/ (accessed Sep. 15, 2022).

[2] “Product Release Management? Definitions and Examples.” https://www.aha.io/roadmapping/guide/release-management (accessed Sep. 15, 2022).

[3] S. Newell, “Release Management.” https://www.productplan.com/glossary/release-management/ (accessed Sep. 15, 2022).

[4] G. Hall, “A Pocket Guide to Product Development & Release Management,” Blackstar, May 21, 2021. https://medium.com/blackstar/a-pocket-guide-to-product-development-release-management-b8240a9591a8 (accessed Sep. 15, 2022).

[5] “What is a Product Release? - Definition from Techopedia,” Techopedia.com.
http://www.techopedia.com/definition/24628/product-release-software (accessed Sep. 15, 2022).

[6] F. Arndt et al., DIN SPEC 3105-1: Open Source Hardware. 2020. doi: 10.31030/3173063.

[7] BuiltByBrainbow, “Version Control for Open Source Hardware,” Instructables. https://www.instructables.com/Version-Control-for-Open-Source-Hardware/ (accessed Sep. 13, 2022).

[8] J. Bonvoisin and R. Mies, “Measuring Openness in Open Source Hardware with the Open-o-Meter,” Procedia CIRP, vol. 78, pp. 388–393, Jan. 2018, doi: 10.1016/j.procir.2018.08.306.

Select a repo