{"id":7420,"date":"2020-11-10T15:41:38","date_gmt":"2020-11-10T14:41:38","guid":{"rendered":"https:\/\/prototype.staging.dev.frachtwerk.de\/?p=7420"},"modified":"2021-10-13T16:45:28","modified_gmt":"2021-10-13T14:45:28","slug":"software-versioning-javascript","status":"publish","type":"post","link":"https:\/\/prototype.staging.dev.frachtwerk.de\/allgemein\/software-versioning-javascript\/","title":{"rendered":"Mastering Software Versioning in JavaScript Projects"},"content":{"rendered":"<div  class=\"tatsu-c4asRnQtSX tatsu-section  tatsu-bg-overlay   tatsu-clearfix\" data-title=\"\"  data-headerscheme=\"background--dark\"><div class='tatsu-section-pad clearfix' data-padding='{\"d\":\"90px 0px 90px 0px\"}' data-padding-top='90px'><div class=\"tatsu-row-wrap  tatsu-wrap tatsu-row-one-col tatsu-row-has-one-cols tatsu-medium-gutter tatsu-reg-cols  tatsu-clearfix tatsu-QXhO16su8n\" ><div  class=\"tatsu-row \" ><div  class=\"tatsu-column  tatsu-bg-overlay tatsu-one-col tatsu-column-image-none tatsu-column-effect-none  tatsu-eSuK6NeG6\"  data-parallax-speed=\"0\" style=\"\"><div class=\"tatsu-column-inner \" ><div class=\"tatsu-column-pad-wrap\"><div class=\"tatsu-column-pad\" ><div  class=\"tatsu-module tatsu-inline-text clearfix tatsu-hbntKAb6c   \" ><style>.tatsu-hbntKAb6c .tatsu-inline-text-inner{width: 100%;text-align: left;}.tatsu-hbntKAb6c.tatsu-inline-text{margin: 0px 0px 60px 0px;}@media only screen and (max-width: 767px) {.tatsu-hbntKAb6c .tatsu-inline-text-inner{width: 100%;}}<\/style><div class=\"tatsu-inline-text-inner tatsu-align-center\">\n<p><span class=\"fs-s\"><em><span class=\"palette-2 fs-s\">Originally published at <\/span><a style=\"color: #1395b8;\" href=\"https:\/\/muetsch.io\/modern-reactive-web-apis-with-graphql-go-and-server-sent-events-part-1.html\">muetsch.io<\/a> <span class=\"palette-2 fs-s\">on Nov<time title=\"Monday, June 8, 2020, 2:00:00 AM\" datetime=\"2020-06-08T00:00:00Z\"> 07, 2020<\/time><\/span><\/em><\/span><\/p>\n<\/div><\/div><div  class=\"tatsu-module tatsu-inline-text clearfix tatsu-_EW6xbQge   \" ><style>.tatsu-_EW6xbQge .tatsu-inline-text-inner{width: 100%;text-align: left;}@media only screen and (max-width: 767px) {.tatsu-_EW6xbQge .tatsu-inline-text-inner{width: 100%;}}<\/style><div class=\"tatsu-inline-text-inner tatsu-align-center\">\n<h2>Introduction<\/h2>\n<p>A frequently overlooked aspect of software development is the proper versioning of code. Consistent and descriptive version numbers not only help developers keep track of their own work, but can also inform users of your software about what to expect from a new release. While versioning is especially important for libraries and frameworks which other projects depend on, benefits apply to standalone applications equally.<\/p>\n<p>In this article, we introduce techniques, conventions, and tooling that helped us establish a robust way of versioning our JavaScript- and\/or TypeScript-based software projects.<\/p>\n<\/div><\/div><div  class=\"tatsu-module tatsu-inline-text clearfix tatsu-xnY9W7WYn   \" ><style>.tatsu-xnY9W7WYn .tatsu-inline-text-inner{width: 100%;text-align: left;}@media only screen and (max-width: 767px) {.tatsu-xnY9W7WYn .tatsu-inline-text-inner{width: 100%;}}<\/style><div class=\"tatsu-inline-text-inner tatsu-align-center\">\n<h2 id=\"Concepts\">Concepts<\/h2>\n<h3 id=\"Semantic-Versioning\">Semantic Versioning<\/h3>\n<p>One of the most important aspects to think of when it comes to versioning is the version number itself. Before caring about tooling and others, you need to come up with syntax and semantics for it.<\/p>\n<p>A concept that is well established among open source software projects is <a href=\"https:\/\/semver.org\/\" target=\"_blank\" rel=\"noopener noreferrer\">Semantic Versioning<\/a>, or <em>SemVer<\/em>. When following this specification, a version number consists of three digits separated by dots, like <code>[1.5.4]<\/code> or, more formally [..], where each individual part has a meaning:<\/p>\n<ul>\n<li><code>[MAJOR]<\/code>: Incrementing it indicates that there have been fundamental changes to the software and the new version is most likely not backward-compatible with the previous one.<\/li>\n<li><code>[MINOR]<\/code>: Essentially indicates that new features were added, but backward-compatibiltiy is still guaranteed.<\/li>\n<li><code>[PATCH]<\/code> or <code>[BUG FIX]<\/code>: Gives a hint that minor changes or bug fixes had been introduced recently.<\/li>\n<\/ul>\n<p>Strictly following these semantics helps to maintain a common understanding of what a certain version means and what to expect from a new release.<\/p>\n<h3 id=\"Conventional-Commits\">Conventional Commits<\/h3>\n<p>The second concept that we committed ourselves to follow is <a href=\"https:\/\/www.conventionalcommits.org\/en\/v1.0.0\/#summary\" target=\"_blank\" rel=\"noopener noreferrer\">Conventional Commits<\/a>. Similar to semantic versioning, the conventional commits specification provides common syntax and semantics for information provided by a developer. However, in this case, the convention is not about the version number itself, but about the commit messages composed by developers when checking in new code into version control. The goal is to standardize their format and make them machine-readable to a certain extent.<\/p>\n<p>When following conventional commits, a commit message essentially has to be prefixed with one of a few keywords.<\/p>\n<ul>\n<li><code>[fix:]<\/code> &ndash; A commit message with this prefix indicates a bug fix<\/li>\n<li><code>[feat:]<\/code> &ndash; A commit message with this prefix indicates the introduction of a new feature or functionality<\/li>\n<li><code>[refactor:]<\/code> &ndash; A commit with, whose message is prefixed like this, contains code refactorings, i.e. internal, technical modifications of the implementation of certain logic<\/li>\n<li><code>[chore:]<\/code> &ndash; This prefix indicates minor, miscellaneous changes of any type, that do not necessarily affect the user immediately<\/li>\n<li><code>[BREAKING CHANGE!:]<\/code> A commit message with this prefix warns about comprehensive, fundamental changes and indicates that the newly released version is likely to be incompatible with the previous one<\/li>\n<\/ul>\n<p>The conventional commits specification comprises a few more keywords and also allows developers to come up with custom ones. However, these are the most relevant ones.<\/p>\n<\/div><\/div><div  class=\"tatsu-module tatsu-inline-text clearfix tatsu-pqp5VmbYh   \" ><style>.tatsu-pqp5VmbYh .tatsu-inline-text-inner{width: 100%;text-align: left;}@media only screen and (max-width: 767px) {.tatsu-pqp5VmbYh .tatsu-inline-text-inner{width: 100%;}}<\/style><div class=\"tatsu-inline-text-inner tatsu-align-center\">\n<h2 id=\"Tooling\">Tooling<\/h2>\n<p>When having paid attention, one might have recognized a few similarities in the semantics of conventional commits and semantic versioning. Commits with <code>[fix]<\/code>-changes correspond to the <code>[PATCH]<\/code> version, <code>[feat]<\/code> goes well with the <code>[MINOR]<\/code> version and <code>[BREAKING CHANGE]<\/code>es will inevitably result in a new <code>[MAJOR]<\/code> version.<\/p>\n<p>As a consequence of following the above conventions, we enabled our project for an automated versioning workflow.<\/p>\n<h3 id=\"standard-version-CLI\">standard-version CLI<\/h3>\n<p><a href=\"https:\/\/www.npmjs.com\/package\/standard-version\" target=\"_blank\" rel=\"noopener noreferrer\">standard-version<\/a> is a JavaScript tool that utilizes conventional commits to automatically enforce semantic versioning. Moreover, it is capable of automatically generating a changelog in Markdown format, which developers can provide their users with.<\/p>\n<p>When running <code>[standard-version]<\/code>, the tool scans your commit history since when it was last executed, searches for fixes, feats, or breaking changes, and adapts the project&rsquo;s version accordingly.<\/p>\n<p>To add it to an existing project, all you need to do is:<\/p>\n<p>&nbsp;1. Install it as a dependency<\/p>\n<\/div><\/div><div  class=\"tatsu-module tatsu-text-block-wrap tatsu-Ty6tRdwJO  \"><div class=\"tatsu-text-inner tatsu-align-center  clearfix\" ><style>.tatsu-Ty6tRdwJO.tatsu-text-block-wrap .tatsu-text-inner{width: 100%;text-align: left;background-color: rgba(49,49,49,1);border-radius: 6px;padding: 10px 30px 10px 30px;color: #ffffff ;}.tatsu-Ty6tRdwJO .tatsu-text-inner *{color: #ffffff ;}<\/style>\n<p><span class=\"line\">$ yarn add -D standard-version <span class=\"comment\" style=\"color: #999999;\"># (or npm i &#8211;save-dev standard-version)<\/span><\/span><\/p>\n<\/div><\/div><div  class=\"tatsu-module tatsu-inline-text clearfix tatsu-6-gwlowc1   \" ><style>.tatsu-6-gwlowc1 .tatsu-inline-text-inner{width: 100%;text-align: left;}@media only screen and (max-width: 767px) {.tatsu-6-gwlowc1 .tatsu-inline-text-inner{width: 100%;}}<\/style><div class=\"tatsu-inline-text-inner tatsu-align-center\">\n<p>\u00a02. Optionally add it as an NPM script to your <code><em>package.json<\/em><\/code><\/p>\n<\/div><\/div><div  class=\"tatsu-module tatsu-text-block-wrap tatsu-ZFRNDtvYe  \"><div class=\"tatsu-text-inner tatsu-align-center  clearfix\" ><style>.tatsu-ZFRNDtvYe.tatsu-text-block-wrap .tatsu-text-inner{width: 100%;text-align: left;background-color: rgba(49,49,49,1);border-radius: 6px;padding: 10px 30px 10px 30px;color: #ffffff ;}.tatsu-ZFRNDtvYe .tatsu-text-inner *{color: #ffffff ;}<\/style>\n<pre><span class=\"line\">{<\/span>\n<span class=\"line\">\u00a0\u00a0\u00a0\u00a0 <span class=\"attr\">\"name\"<\/span>: <span class=\"string\">\"your-cool-project\"<\/span>,<\/span>\n<span class=\"line\">\u00a0\u00a0\u00a0\u00a0 <span class=\"attr\">\"version:\"<\/span>: <span class=\"string\">\"0.0.1\"<\/span>,<\/span>\n<span class=\"line\">\u00a0\u00a0\u00a0\u00a0 ...<\/span>\n<span class=\"line\">\u00a0\u00a0\u00a0\u00a0 <span class=\"string\">\"scripts:\"<\/span> {<\/span>\n<span class=\"line\">\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 <span class=\"attr\">\"release\"<\/span>: <span class=\"string\">\"standard-version\"<\/span><\/span>\n<span class=\"line\">\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 ...<\/span>\n<span class=\"line\">\u00a0\u00a0\u00a0\u00a0 }<\/span>\n<span class=\"line\">\u00a0\u00a0\u00a0\u00a0 ...<\/span>\n<span class=\"line\">}\n<\/span><\/pre>\n<\/div><\/div><div  class=\"tatsu-module tatsu-inline-text clearfix tatsu-7K3zEh884   \" ><style>.tatsu-7K3zEh884 .tatsu-inline-text-inner{width: 100%;text-align: left;}@media only screen and (max-width: 767px) {.tatsu-7K3zEh884 .tatsu-inline-text-inner{width: 100%;}}<\/style><div class=\"tatsu-inline-text-inner tatsu-align-center\">\n<h2 id=\"Release-Workflow\">Release Workflow<\/h2>\n<p>After the development team has committed to consequently follow the conventional commits specification and all tooling is set up, a typical workflow to release new versions of your software might look like so.<\/p>\n<p>Once a new version is ready to be released, i.e. at the end of a sprint, a developer executes <code>[yarn release]<\/code> (or <code>[npm run release]<\/code>) to kick off <code>[standard-version]<\/code>. As a result \u2026<\/p>\n<ol>\n<li>\u2026 the project\u2019s commit history is scanned to determine which part of the version number needs to be incremented<\/li>\n<li>\u2026 the <code>[version]<\/code> property of the project\u2019s top-level [<code>package.json]<\/code> is set to the new version<\/li>\n<li>\u2026 a <code>[CHANGELOG.md]<\/code> file is written, containing separate sections for features and bug fixes<\/li>\n<li>\u2026 the changes are committed to Git<\/li>\n<li>\u2026 the new commit is given a Git tag corresponding to the new version<\/li>\n<\/ol>\n<p>Depending on your setup, a push to the remote repository might kick off your CI\/CD workflow, which may automatically build a new Docker image with the newly introduced tag and push it to a public or private registry. Using tools like <a href=\"https:\/\/github.com\/containrrr\/watchtower\" target=\"_blank\" rel=\"noopener noreferrer\">Watchtower<\/a>, the new image might even be rolled out to production automatically.<\/p>\n<p>The only manual steps required in this workflow were a single <code>yarn release<\/code> command and a Git push. Nothing more, nothing less.<\/p>\n<\/div><\/div><div  class=\"tatsu-module tatsu-inline-text clearfix tatsu-x-bC4T1fF   \" ><style>.tatsu-x-bC4T1fF .tatsu-inline-text-inner{width: 100%;text-align: left;}@media only screen and (max-width: 767px) {.tatsu-x-bC4T1fF .tatsu-inline-text-inner{width: 100%;}}<\/style><div class=\"tatsu-inline-text-inner tatsu-align-center\">\n<h2 id=\"Conclusion\">Conclusion<\/h2>\n<p>The above workflow has proven to be a convenient and consistent way of managing and releasing new versions of our JavaScript- and TypeScript-based frontend-, backend- and library projects and is even more beneficial with proper CI\/CD pipelines and tooling like <a href=\"https:\/\/gitlab.com\/\" target=\"_blank\" rel=\"noopener noreferrer\">GitLab<\/a>, <a href=\"https:\/\/docker.io\/\" target=\"_blank\" rel=\"noopener noreferrer\">Docker<\/a>, <a href=\"https:\/\/github.com\/containrrr\/watchtower\" target=\"_blank\" rel=\"noopener noreferrer\">Watchtower<\/a>, <a href=\"https:\/\/portainer.io\/\" target=\"_blank\" rel=\"noopener noreferrer\">Portainer<\/a>, and others. It might even be adapted to projects written in other programming languages.<\/p>\n<\/div><\/div><div  class=\"tatsu-module tatsu-inline-text clearfix tatsu-L91cNSnzB   \" ><style>.tatsu-L91cNSnzB .tatsu-inline-text-inner{width: 100%;text-align: left;}.tatsu-L91cNSnzB.tatsu-inline-text{margin: 0px 0px 60px 0px;}@media only screen and (max-width: 767px) {.tatsu-L91cNSnzB .tatsu-inline-text-inner{width: 100%;}}<\/style><div class=\"tatsu-inline-text-inner tatsu-align-center\">\n<p><span class=\"fs-s\"><em><span class=\"palette-2 fs-s\">Originally published at <\/span><a style=\"color: #1395b8;\" href=\"https:\/\/muetsch.io\/modern-reactive-web-apis-with-graphql-go-and-server-sent-events-part-1.html\">muetsch.io<\/a> <span class=\"palette-2 fs-s\">on Nov<time title=\"Monday, June 8, 2020, 2:00:00 AM\" datetime=\"2020-06-08T00:00:00Z\"> 07, 2020<\/time><\/span><\/em><\/span><\/p>\n<\/div><\/div><\/div><\/div><div class = \"tatsu-column-bg-image-wrap\"><div class = \"tatsu-column-bg-image tatsu-bg-lazyload\" data-src = \"\"><\/div><\/div><div class=\"tatsu-overlay tatsu-column-overlay tatsu-animate-none\" ><\/div><\/div><style>.tatsu-row > .tatsu-eSuK6NeG6.tatsu-column{width: 100%;}.tatsu-eSuK6NeG6.tatsu-column > .tatsu-column-inner > .tatsu-column-overlay{mix-blend-mode: normal;}.tatsu-eSuK6NeG6 > .tatsu-column-inner > .tatsu-top-divider{z-index: 9999;}.tatsu-eSuK6NeG6 > .tatsu-column-inner > .tatsu-bottom-divider{z-index: 9999;}.tatsu-eSuK6NeG6 > .tatsu-column-inner > .tatsu-left-divider{z-index: 9999;}.tatsu-eSuK6NeG6 > .tatsu-column-inner > .tatsu-right-divider{z-index: 9999;}@media only screen and (max-width:1377px) {.tatsu-row > .tatsu-eSuK6NeG6.tatsu-column{width: 100%;}}@media only screen and (min-width:768px) and (max-width: 1024px) {.tatsu-row > .tatsu-eSuK6NeG6.tatsu-column{width: 100%;}}@media only screen and (max-width: 767px) {.tatsu-row > .tatsu-eSuK6NeG6.tatsu-column{width: 100%;}}<\/style><\/div><\/div><\/div><\/div><div class=\"tatsu-section-background-wrap\"><div class = \"tatsu-section-background tatsu-bg-lazyload\" data-src = \"\"><\/div><\/div><div class=\"tatsu-overlay tatsu-section-overlay\"><\/div><style>.tatsu-c4asRnQtSX .tatsu-section-pad{padding: 90px 0px 90px 0px;}.tatsu-c4asRnQtSX .tatsu-section-offset-wrap{transform: translateY(-0px);}.tatsu-c4asRnQtSX > .tatsu-bottom-divider{z-index: 9999;}.tatsu-c4asRnQtSX > .tatsu-top-divider{z-index: 9999;}.tatsu-c4asRnQtSX .tatsu-section-overlay{mix-blend-mode: normal;}<\/style><\/div>\n","protected":false},"excerpt":{"rendered":"<div><a href=\"https:\/\/prototype.staging.dev.frachtwerk.de\/allgemein\/software-versioning-javascript\/\" class=\"exp-read-more exp-read-more-underlined\">Read More<\/a><\/div>\n","protected":false},"author":11,"featured_media":6191,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_vp_format_video_url":"","_vp_image_focal_point":[]},"categories":[1,50,11],"tags":[59,58],"_links":{"self":[{"href":"https:\/\/prototype.staging.dev.frachtwerk.de\/wp-json\/wp\/v2\/posts\/7420"}],"collection":[{"href":"https:\/\/prototype.staging.dev.frachtwerk.de\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/prototype.staging.dev.frachtwerk.de\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/prototype.staging.dev.frachtwerk.de\/wp-json\/wp\/v2\/users\/11"}],"replies":[{"embeddable":true,"href":"https:\/\/prototype.staging.dev.frachtwerk.de\/wp-json\/wp\/v2\/comments?post=7420"}],"version-history":[{"count":6,"href":"https:\/\/prototype.staging.dev.frachtwerk.de\/wp-json\/wp\/v2\/posts\/7420\/revisions"}],"predecessor-version":[{"id":7727,"href":"https:\/\/prototype.staging.dev.frachtwerk.de\/wp-json\/wp\/v2\/posts\/7420\/revisions\/7727"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/prototype.staging.dev.frachtwerk.de\/wp-json\/wp\/v2\/media\/6191"}],"wp:attachment":[{"href":"https:\/\/prototype.staging.dev.frachtwerk.de\/wp-json\/wp\/v2\/media?parent=7420"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/prototype.staging.dev.frachtwerk.de\/wp-json\/wp\/v2\/categories?post=7420"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/prototype.staging.dev.frachtwerk.de\/wp-json\/wp\/v2\/tags?post=7420"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}