knowledge-kitchen / course-notes

class: center, middle # Release Management An organized approach to versioning software releases. --- # Agenda 1. [Overview](#overview) 1. [Semantic Versioning](#semantic-versioning) 1. [Calendar Versioning](#calendar-versioning) 1. [Git Tags](#git-tags) 1. [GitHub Releases](#github) 1. [Conclusions](#conclusions) --- name: overview # Overview -- ## Concept Release management is the streamlined approach to issuing software releases. --- template: overview ## Contents What is in a release? The following are some common contents: -- - the working software -- - configuration files -- - data files, including any data migration scripts -- - an installation program -- - documentation -- - marketing and promotion materials --- template: overview ## Release Timing The date on which a release is published is often dependent upon a number of factors: -- - level of effort to complete the release -- - the release schedules of technical dependencies -- - the release schedules of the competition -- - marketing parternships and promotions -- - business reasons why one particular date might be better than another --- name: semantic-versioning # Semantic Versioning -- ## Concept Software versions using the [Semantic Versioning](https://semver.org/) system take the form of: `X`.`Y`.`Z` -- e.g. `Ubuntu 20.04.3`, `MacOS 13.4.1`, `Python 3.9.7`, `Node.js 16.9.1` -- Where... - `X` is the **major version** number - `Y` is the **minor version** number - `Z` is the **patch** number --- template: semantic-versioning ## Prefixes There is some debate as to whether a version number should be prefixed with a `v` as in `v1.0.2` instead of simply `1.0.2`. -- - For our purposes, it doesn't matter. See more discussion about this [here](https://stackoverflow.com/questions/21639437/git-flow-release-branches-and-tags-with-or-without-v-prefix/21639868). --- name: rules template: semantic-versioning ## Rules Semantic Versioning involves 12 rules. The first 8 are the most important and are included here. --- template: rules ### Rule 1: Public API Software using Semantic Versioning **must** declare a [public API](https://stackoverflow.com/questions/9463613/what-does-public-api-mean-in-semantic-versioning). This API could be declared in the code itself or exist strictly in documentation. However it is done, it should be precise and comprehensive. --- template: rules ### Rule 2: Version Number Format A normal version number **must** take the form `X`.`Y`.`Z` where `X`, `Y`, and `Z` are non-negative integers, and **must not** contain leading zeroes. `X` is the major version, `Y` is the minor version, and `Z` is the patch version. Each element **must** increase numerically. For instance: `1`.`9`.`0` -> `1`.`10`.`0` -> `1`.`11`.`0`. --- template: rules ### Rule 3: Immutability of Versions Once a versioned package has been released, the contents of that version **must not** be modified. Any modifications **must** be released as a new version. --- template: rules ### Rule 4: In-Develepment API Version Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable. --- template: rules ### Rule 5: Initial Public API Version Version `1`.`0`.`0` defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes. --- template: rules ### Rule 6: Patch Versions Patch version Z (`x`.`y`.`Z` | `x` > 0) **must** be incremented if only backwards compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior. --- template: rules ### Rule 7: Minor Versions Minor version Y (`x`.`Y`.`z` | `x` > 0) **must** be incremented if new, backwards compatible functionality is introduced to the public API. It **must** be incremented if any public API functionality is marked as deprecated. It MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. Patch version **must** be reset to 0 when minor version is incremented. --- template: rules ### Rule 8: Major Versions Major version X (`X`.`y`.`z` | `X` > 0) **must** be incremented if any backwards incompatible changes are introduced to the public API. It MAY include minor and patch level changes. Patch and minor version **must** be reset to 0 when major version is incremented. --- template: semantic-versioning ## Criticisms While Semantic Versioning is arguably the most popular formalized approach to the problem versioning, it does have its critics. - For example: Rich Hickey's [Semantic Versioning is a Lie](https://www.youtube.com/watch?v=oyLBGkS5ICk&t=1793s) and Hynek Schlawack's [Semantic Versioning Will Not Save You](https://hynek.me/articles/semver-will-not-save-you/) -- - Criticism tends to focus on the fact that, in practice, patches and minor version updates often result in broken applications, despite the best of intentions. -- - In that context, semantic versioning's clear rules seem like wishful thinking that belies a more complex reality. --- name: calendar-versioning # Calendar Versioning -- ## Overview [Calendar versioning](https://calver.org/) is a simple approach to versioning software releases. It uses the date of the release as the version number. -- - The date is the only version number. -- - There is no concept of a major, minor, or patch version. -- - No concept of a "public API". -- - The spec provides flexibility in how the date is formatted. -- Essentially a fancy version of the time-tested technique of naming your files with the date in the filename. --- template: calendar-versioning ## When to use Calendar Versioning is a good choice when: -- - your project features a large or constantly-changing scope (i.e. new versions are difficult to plan ahead) -- - your project is time-sensitive (i.e. time is a major factor driving new releases) -- - other external changes drive new project releases (i.e. new releases are not driven by planned changes in functionality) --- template: calendar-versioning ## Example Your old `my-homework-01-10-2023.txt` file now becomes a `my-homework` repository tagged with version `2023.01.10` --- template: calendar-versioning ## Date format While Calendar Versioning supports multiple date formats, when in doubt, use `YYYY.MM.DD`, where `YYYY` is the four-digit year, `MM` is the zero-padded month, and `DD` is the zero-padded day. -- - This simplifies sorting by date. The standard date format in the US, `MM`.`DD`.`YYYY`, is an embarrassment for sorting. -- e.g. do this: `2023.01.10`, not this: `01.10.2023` --- name: git-tags # Git Tags -- ## Concept Git's [tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging) features can be used to mark the repository at a moment in time as a particular release. --- template: git-tags ## Create Tag Create a tag on the currently checked-out branch, labeling it as release version `1`.`0`.`0`: ```bash git tag v1.0.0 ``` -- ... or, if using a calendar versioning tag: ```bash git tag 2023.01.10 ``` --- template: git-tags ## Create Tag with a Message Leave an optional message to go along with a tag. ```bash git tag -a v1.0.0 -m "initial version of the coffee grind future fineness predictive algorithm" ``` --- template: git-tags ## Push Tag Push the release to an upstream remote repository, such as GitHub: ```bash git push origin v1.0.0 ``` --- template: git-tags ## Switch to Tag Checkout code from the `main` branch as it was at release version `1`.`0`.`0`: ```bash git checkout -b main v1.0.0 ``` --- template: git-tags --- name: github # GitHub Releases -- ## Concept GitHub repositories have a '[Releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases)' page, linked from sub-navigation links in the 'Code' tab. -- GitHub's Releases functionality can complement the Git tag for a release and make it more intuitive to find a project's official releases. --- name: conclusions # Conclusions Thank you. Bye.