HackMD
  • Beta
    Beta  Get a sneak peek of HackMD’s new design
    Turn on the feature preview and give us feedback.
    Go → Got it
      • Create new note
      • Create a note from template
    • Beta  Get a sneak peek of HackMD’s new design
      Beta  Get a sneak peek of HackMD’s new design
      Turn on the feature preview and give us feedback.
      Go → Got it
      • Sharing Link copied
      • /edit
      • View mode
        • Edit mode
        • View mode
        • Book mode
        • Slide mode
        Edit mode View mode Book mode Slide mode
      • Note Permission
      • Read
        • Only me
        • Signed-in users
        • Everyone
        Only me Signed-in users Everyone
      • Write
        • Only me
        • Signed-in users
        • Everyone
        Only me Signed-in users Everyone
      • More (Comment, Invitee)
      • Publishing
        Please check the box to agree to the Community Guidelines.
        Everyone on the web can find and read all notes of this public team.
        After the note is published, everyone on the web can find and read this note.
        See all published notes on profile page.
      • Commenting Enable
        Disabled Forbidden Owners Signed-in users Everyone
      • Permission
        • Forbidden
        • Owners
        • Signed-in users
        • Everyone
      • Invitee
      • No invitee
      • Options
      • Versions and GitHub Sync
      • Transfer ownership
      • Delete this note
      • Template
      • Save as template
      • Insert from template
      • Export
      • Dropbox
      • Google Drive Export to Google Drive
      • Gist
      • Import
      • Dropbox
      • Google Drive Import from Google Drive
      • Gist
      • Clipboard
      • Download
      • Markdown
      • HTML
      • Raw HTML
    Menu Sharing Create Help
    Create Create new note Create a note from template
    Menu
    Options
    Versions and GitHub Sync Transfer ownership Delete this note
    Export
    Dropbox Google Drive Export to Google Drive Gist
    Import
    Dropbox Google Drive Import from Google Drive Gist Clipboard
    Download
    Markdown HTML Raw HTML
    Back
    Sharing
    Sharing Link copied
    /edit
    View mode
    • Edit mode
    • View mode
    • Book mode
    • Slide mode
    Edit mode View mode Book mode Slide mode
    Note Permission
    Read
    Only me
    • Only me
    • Signed-in users
    • Everyone
    Only me Signed-in users Everyone
    Write
    Only me
    • Only me
    • Signed-in users
    • Everyone
    Only me Signed-in users Everyone
    More (Comment, Invitee)
    Publishing
    Please check the box to agree to the Community Guidelines.
    Everyone on the web can find and read all notes of this public team.
    After the note is published, everyone on the web can find and read this note.
    See all published notes on profile page.
    More (Comment, Invitee)
    Commenting Enable
    Disabled Forbidden Owners Signed-in users Everyone
    Permission
    Owners
    • Forbidden
    • Owners
    • Signed-in users
    • Everyone
    Invitee
    No invitee
       owned this note    owned this note      
    Published Linked with GitHub
    Like BookmarkBookmarked
    Subscribed
    • Any changes
      Be notified of any changes
    • Mention me
      Be notified of mention me
    • Unsubscribe
    Subscribe
    --- title: Versioning and Releasing Open Hardware content description: This lesson is focused on best practices and recommendations to distribute open hardware content. A good distribution approach for open hardware approach should address versioning and releasing planning. authors: Jerry de Vos, Jose Urra --- # Versioning and Releasing Open Hardware content [![License: CC BY 4.0](https://img.shields.io/badge/License-CC_BY_4.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7195696.svg)](https://doi.org/10.5281/zenodo.7195696) **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. :::info **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](https://www.oshwa.org/definition/#:~:text=Open%20source%20hardware%20is%20hardware,for%20making%20modifications%20to%20it). **This lesson focuses on the activities associated to the distribution of open hardware design documents/data.** ### Some useful definitions and ideas :::warning :warning: 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](https://www.techopedia.com/definition/24628/product-release-software) - 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](https://www.techopedia.com/definition/25977/software-versioning) - :warning: 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](https://semver.org/) 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. :::warning ![](https://i.imgur.com/jhZqFrI.png) A small portion of a version tree of RepRap printers retrieved from [link](https://www.reprap.org/mediawiki/images/c/c5/2012-12-15-clone-wars-genealogy-90-clones-peq.png) ::: :::spoiler **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](https://github.com), [Wikifactory](https://wikifactory.com), [Gitlab](https://gitlab.com), [Hackaday](hackaday.io), [Thingiverse](https://thingiverse.com), among many others. OSWHA has a list of interesting channels that include [HardwareX](https://www.sciencedirect.com/journal/hardwarex), [The Journal of Open Hardware](https://openhardware.metajnl.com/) and [The Journal of Open Engineering](https://www.tjoe.org/). ## 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. :point_right: [Read more about alpha and beta testing](https://www.softwaretestinghelp.com/what-is-alpha-testing-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](https://www.oshwa.org/definition/#:~:text=Open%20source%20hardware%20is%20hardware,for%20making%20modifications%20to%20it). **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.** :::success **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 :::info :information_source: The following list of tools have quite some overlap with **[our previous documentation lesson](https://hackmd.io/C1eJ3lmSQ7ijtGi0FtTcGg)**. This is because design documentation is the most important component of a release. ::: |Tools & Methods | Comments and observations| |----|-----| |[Open Hardware Canvas](https://curriculum.openhardware.space/articles/01-welcome-to-ohm/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](https://certification.oshwa.org/)| 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](https://gitlab.com/OSEGermany/OHS-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](https://gitlab.com/OSEGermany/OHS-3105)| |[Semantic versioning](https://semver.org/) | A naming convention for data packages/repositories that provides information about a project's history and status | [Release management with github](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) | 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](https://en.oho.wiki/wiki/Technical_documentation) | 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](https://okh.makernet.org/form) | 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 :::info :information_source: 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. ## Thanks to This lesson is made possible by: Jerry de Vos, Jose Urra ## Contact Link to [Academy website](https://openhardware.academy)

    Import from clipboard

    Advanced permission required

    Your current role can only read. Ask the system administrator to acquire write and comment permission.

    This team is disabled

    Sorry, this team is disabled. You can't edit this note.

    This note is locked

    Sorry, only owner can edit this note.

    Reach the limit

    Sorry, you've reached the max length this note can be.
    Please reduce the content or divide it to more notes, thank you!

    Import from Gist

    Import from Snippet

    or

    Export to Snippet

    Are you sure?

    Do you really want to delete this note?
    All users will lost their connection.

    Create a note from template

    Create a note from template

    Oops...
    This template is not available.


    Upgrade

    All
    • All
    • Team
    No template found.

    Create custom template


    Upgrade

    Delete template

    Do you really want to delete this template?

    This page need refresh

    You have an incompatible client version.
    Refresh to update.
    New version available!
    See releases notes here
    Refresh to enjoy new features.
    Your user state has changed.
    Refresh to load new user state.

    Sign in

    Forgot password

    or

    By clicking below, you agree to our terms of service.

    Sign in via Facebook Sign in via Twitter Sign in via GitHub Sign in via Dropbox

    New to HackMD? Sign up

    Help

    • English
    • 中文
    • Français
    • Deutsch
    • 日本語
    • Español
    • Català
    • Ελληνικά
    • Português
    • italiano
    • Türkçe
    • Русский
    • Nederlands
    • hrvatski jezik
    • język polski
    • Українська
    • हिन्दी
    • svenska
    • Esperanto
    • dansk

    Documents

    Tutorials

    Book Mode Tutorial

    Slide Mode Tutorial

    YAML Metadata

    Contacts

    Facebook

    Twitter

    Feedback

    Send us email

    Resources

    Releases

    Pricing

    Blog

    Policy

    Terms

    Privacy

    Cheatsheet

    Syntax Example Reference
    # Header Header 基本排版
    - Unordered List
    • Unordered List
    1. Ordered List
    1. Ordered List
    - [ ] Todo List
    • Todo List
    > Blockquote
    Blockquote
    **Bold font** Bold font
    *Italics font* Italics font
    ~~Strikethrough~~ Strikethrough
    19^th^ 19th
    H~2~O H2O
    ++Inserted text++ Inserted text
    ==Marked text== Marked text
    [link text](https:// "title") Link
    ![image alt](https:// "title") Image
    `Code` Code 在筆記中貼入程式碼
    ```javascript
    var i = 0;
    ```
    var i = 0;
    :smile: :smile: Emoji list
    {%youtube youtube_id %} Externals
    $L^aT_eX$ LaTeX
    :::info
    This is a alert area.
    :::

    This is a alert area.

    Versions

    Versions and GitHub Sync

    Sign in to link this note to GitHub Learn more
    This note is not linked with GitHub Learn more
     
    Add badge Pull Push GitHub Link Settings
    Upgrade now

    Version named by    

    More Less
    • Edit
    • Delete

    Note content is identical to the latest version.
    Compare with
      Choose a version
      No search result
      Version not found

    Feedback

    Submission failed, please try again

    Thanks for your support.

    On a scale of 0-10, how likely is it that you would recommend HackMD to your friends, family or business associates?

    Please give us some advice and help us improve HackMD.

     

    Thanks for your feedback

    Remove version name

    Do you want to remove this version name and description?

    Transfer ownership

    Transfer to
      Warning: is a public team. If you transfer note to this team, everyone on the web can find and read this note.

        Link with GitHub

        Please authorize HackMD on GitHub

        Please sign in to GitHub and install the HackMD app on your GitHub repo. Learn more

         Sign in to GitHub

        HackMD links with GitHub through a GitHub App. You can choose which repo to install our App.

        Push the note to GitHub Push to GitHub Pull a file from GitHub

          Authorize again
         

        Choose which file to push to

        Select repo
        Refresh Authorize more repos
        Select branch
        Select file
        Select branch
        Choose version(s) to push
        • Save a new version and push
        • Choose from existing versions
        Available push count

        Upgrade

        Pull from GitHub

         
        File from GitHub
        File from HackMD

        GitHub Link Settings

        File linked

        Linked by
        File path
        Last synced branch
        Available push count

        Upgrade

        Danger Zone

        Unlink
        You will no longer receive notification when GitHub file changes after unlink.

        Syncing

        Push failed

        Push successfully