{"id":42815,"date":"2022-03-25T15:36:32","date_gmt":"2022-03-25T15:36:32","guid":{"rendered":"https:\/\/polarising.com\/?p=42815"},"modified":"2022-08-29T15:49:43","modified_gmt":"2022-08-29T15:49:43","slug":"keep-track-of-your-software-2-2","status":"publish","type":"post","link":"https:\/\/polarising.com\/techinside\/keep-track-of-your-software-2-2\/","title":{"rendered":"Keep track of your Software (2\/2)"},"content":{"rendered":"\n<div style=\"height:50px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p>While developing a project, it is not uncommon that the project is divided into several stages. Using Scrum terminology, the project has several sprints in which some predetermined features are delivered, and at the end of the sprint one of these deliverables is the handover, helping to identify what was done within the sprint.<\/p>\n\n\n\n<p>Although the above is applied to the Scrum framework, the principle is common to every software project, regardless of the amount of work done.<\/p>\n\n\n\n<p>It is considered a best practice in software development that each artifact delivered is followed by a document that specifies the changes that were made. In some methods such as Release Management, it is required that this document is delivered with the project.<\/p>\n\n\n\n<p>In almost all practices, this document is called CHANGELOG, and in some Git host providers (such as Gitlab), you can add a CHANGELOG template to aid the fulfilment.<\/p>\n\n\n\n<div style=\"height:50px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"the-data-modeling-solution-that-will-deliver-the-future\">What is a Changelog<\/h2>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p>The Changelog file has a log of changes to the project. It is a simple and structured text file, and reflects the changes straight to the point.&nbsp;<strong>It is NOT&nbsp;<\/strong>a trash bin to dump information; it<strong>&nbsp;is NOT<\/strong>&nbsp;a file where you leave the history of the git. It is a useful file that we can consult at any time and check what was done.<\/p>\n\n\n\n<p>Although there is no ISO standard or RFC document that specifies the structure of the Changelog, the industry follows a format suggested by the website&nbsp;<a href=\"https:\/\/keepachangelog.com\/en\/1.0.0\/\" target=\"_blank\" rel=\"noreferrer noopener\">keepachangelog.com<\/a>&nbsp;and uses the semantic versioning.<\/p>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<ol class=\"wp-block-list\"><li>Changelog Structure<\/li><\/ol>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p>The Changelog should be very simple, human-readable, and commonly split into three sections:<\/p>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<ul class=\"wp-block-list\"><li>Header<\/li><li>Unreleased<\/li><li>Released<\/li><\/ul>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p>With this structure, the file intends to be analyzed quickly and get the most useful information fast.<\/p>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p><strong>Header<\/strong><\/p>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p>This section is straightforward and usually has information for the reader about the file\u2019s intention and some contact information, although it is not mandatory.<\/p>\n\n\n\n<p>Some Changelogs have minimal information such as:<\/p>\n\n\n\n<p><em># Changelog<\/em><em><\/em><\/p>\n\n\n\n<p><em>All notable changes to this project will be documented in this file.<\/em><\/p>\n\n\n\n<p><em>The format is based on [Keep a Changelog] (<a href=\"https:\/\/keepachangelog.com\/en\/1.0.0\/\" target=\"_blank\" rel=\"noreferrer noopener\">https:\/\/keepachangelog.com\/en\/1.0.0\/<\/a>),<\/em> <em>and this project adheres to [Semantic Versioning](<a href=\"https:\/\/semver.org\/spec\/v2.0.0.html\" target=\"_blank\" rel=\"noreferrer noopener\">https:\/\/semver.org\/spec\/v2.0.0.html<\/a>).<\/em><\/p>\n\n\n\n<p>The structure follows markdown language to appear formatted in git hosts.<\/p>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<div class=\"wp-block-cover is-light has-parallax alignwide\" style=\"background-image:url(https:\/\/polarising.com\/techinside\/wp-content\/uploads\/2022\/04\/semantic-versioning-image-parallax.png)\"><span aria-hidden=\"true\" class=\"has-cyan-bluish-gray-background-color has-background-dim-20 wp-block-cover__gradient-background has-background-dim\"><\/span><div class=\"wp-block-cover__inner-container is-layout-flow wp-block-cover-is-layout-flow\">\n<p class=\"has-text-align-center has-large-font-size\"><\/p>\n<\/div><\/div>\n\n\n\n<div style=\"height:50px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"the-data-modeling-solution-that-will-deliver-the-future\">Unreleased<\/h2>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p>The \u201cUnreleased\u201d section should be the top section (after the \u201cHeader\u201d) and reflects the work that was done but is not published yet.<\/p>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p><em>An example:<\/em><\/p>\n\n\n\n<p><em>## [Unreleased]<\/em><\/p>\n\n\n\n<p><em>### Fixed<\/em><\/p>\n\n\n\n<p><em>GLB-1982 \u2014 Fixed typo in the Web API call.<\/em><\/p>\n\n\n\n<p>While delivering features, fixing bugs, etc., this section will increase and keep track of the work. <\/p>\n\n\n\n<p>When a new release is made, all items in this section become a new version of the \u201cReleased\u201d area.<\/p>\n\n\n\n<div style=\"height:50px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"the-data-modeling-solution-that-will-deliver-the-future\">Released<\/h2>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p>This section reflects the history of the project, what was done when it was done. Reflects all the changes that were made in each version.<\/p>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p>An example (from the&nbsp;<a href=\"https:\/\/keepachangelog.com\/en\/1.0.0\/\" target=\"_blank\" rel=\"noreferrer noopener\">keepachangelog.com<\/a>&nbsp;site):<\/p>\n\n\n\n<p><em>## [0.0.4] \u2014 2014\u201308\u201309<\/em><\/p>\n\n\n\n<p><em>### Added<\/em><\/p>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<ul class=\"wp-block-list\"><li><em>Better explanation of the difference between the file (\u201cCHANGELOG\u201d)<\/em> <em>and its function \u201cthe change log\u201d.<\/em><\/li><\/ul>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p><em>### Changed<\/em><\/p>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<ul class=\"wp-block-list\"><li><em>Refer to a \u201cchange log\u201d instead of a \u201cCHANGELOG\u201d throughout the site<\/em> <em>to differentiate between the file and the purpose of the file \u2014 the<\/em> <em>logging of changes.<\/em><\/li><\/ul>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p><em>### Removed<\/em><\/p>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<ul class=\"wp-block-list\"><li><em>Remove empty sections from CHANGELOG; they occupy too much space and create too much noise in the file. People will have to assume that then missing sections were intentionally left out because they contained no notable changes.<\/em><\/li><\/ul>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p>As we can see for the specified version, this was what was done.<\/p>\n\n\n\n<div style=\"height:50px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"the-data-modeling-solution-that-will-deliver-the-future\">Guidelines for clean \u201cReleased\u201d sections<\/h2>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p>Keeping useful \u201cReleased\u201d sections requires discipline and should follow these guidelines:<\/p>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<ul class=\"wp-block-list\"><li><strong>The latest version comes first. Each section should have the version and release date.<\/strong><\/li><li><strong>The date should follow ISO 8601.<\/strong><\/li><li><strong>Consider following Semantic Versioning.<\/strong><\/li><li><strong>There should be an entry for every single version.<\/strong><\/li><li><strong>Group changes by their type.<\/strong><\/li><li><strong>Each change should be linkable to a work item.<\/strong><\/li><\/ul>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p>Actually, most of all the cleaning rules are common sense. I keep it simple; we can keep a human-readable Changelog.<\/p>\n\n\n\n<div style=\"height:50px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"the-data-modeling-solution-that-will-deliver-the-future\">Changes Types<\/h2>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p>Like I mention before, we should group our changes by their type to have a clean section. So, which change types do we have?<\/p>\n\n\n\n<p>There are only 6 common types referred to in the&nbsp;<a href=\"https:\/\/keepachangelog.com\/en\/1.0.0\/\" target=\"_blank\" rel=\"noopener\">keepachangelog.com<\/a>&nbsp;website that seem to be enough, but you should adapt it to your needs.<\/p>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p>The change types are:<\/p>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p><strong><em>Added<\/em><\/strong><em>: for new features.<\/em><\/p>\n\n\n\n<p><strong><em>Changed:<\/em><\/strong><em>&nbsp;for changes in existing functionality.<\/em><\/p>\n\n\n\n<p><strong><em>Deprecated:<\/em><\/strong><em>&nbsp;for soon-to-be removed features.<\/em><\/p>\n\n\n\n<p><strong><em>Removed:<\/em><\/strong><em>&nbsp;for now, removed parts.<\/em><\/p>\n\n\n\n<p><strong><em>Fixed:<\/em><\/strong><em>&nbsp;for any bug fixes.<\/em><\/p>\n\n\n\n<p><strong><em>Security:<\/em><\/strong><em>&nbsp;in case of vulnerabilities.<\/em><\/p>\n\n\n\n<p>src:&nbsp;<a href=\"https:\/\/keepachangelog.com\/en\/1.0.0\/\" target=\"_blank\" rel=\"noreferrer noopener\">keepachangelog.com<\/a><\/p>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p>As we can see, these types should cover all needs. The most cautious type is the \u201cRemoved\u201d type, since it may imply that by following Semantic Version that could be a breaking change, and we should consider increasing the Major version. The guideline that features should become deprecated before being removed.<\/p>\n\n\n\n<div style=\"height:50px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"the-data-modeling-solution-that-will-deliver-the-future\">Conclusion<\/h2>\n\n\n\n<div style=\"height:30px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p>Having and keeping a changelog is not hard, quite the opposite, but requires discipline. Discipline to follow the guidelines and having structured messages so a human can read the file. Keeping a clean changelog is a powerful tool of the project and in Release Management.<\/p>\n\n\n\n<p>Although only a small set of the team should be able to fill the Changelog, all sections should be aware of the guidelines to edit the file if needed. <\/p>\n\n\n\n<p>To simplify the changelog messages, the software development team may change how they write the commit messages to adopt \u201csmart commits.\u201d It is not recommended to dump git diff logs in the changelogs. However, if the team uses \u201csmart commits,\u201d the work of the guy that fills the change record becomes easier .\ud83d\ude0a<\/p>\n\n\n\n<div style=\"height:50px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<p><strong>Nuno Cancelo<\/strong><br>Polarising\u2019s Microsoft Practice Lead<\/p>\n","protected":false},"excerpt":{"rendered":"<p>While developing a project, it is not uncommon that the project is divided into several stages. Using Scrum terminology, the project has several sprints in which some predetermined features are delivered, and at the end of the sprint one of these deliverables is the handover, helping to identify what was done within the sprint. Although [&hellip;]<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"inline_featured_image":false,"_uag_custom_page_level_css":"","site-sidebar-layout":"default","site-content-layout":"default","ast-site-content-layout":"","site-content-style":"default","site-sidebar-style":"default","ast-global-header-display":"","ast-banner-title-visibility":"","ast-main-header-display":"","ast-hfb-above-header-display":"","ast-hfb-below-header-display":"","ast-hfb-mobile-header-display":"","site-post-title":"","ast-breadcrumbs-content":"","ast-featured-img":"","footer-sml-layout":"","theme-transparent-header-meta":"default","adv-header-id-meta":"","stick-header-meta":"","header-above-stick-meta":"","header-main-stick-meta":"","header-below-stick-meta":"","astra-migrate-meta-layouts":"default","ast-page-background-enabled":"default","ast-page-background-meta":{"desktop":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-gradient":""},"tablet":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-gradient":""},"mobile":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-gradient":""}},"ast-content-background-meta":{"desktop":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-gradient":""},"tablet":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-gradient":""},"mobile":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-gradient":""}},"footnotes":""},"categories":[4],"tags":[],"class_list":["post-42815","post","type-post","status-publish","format-standard","hentry","category-technology"],"uagb_featured_image_src":{"full":false,"thumbnail":false,"medium":false,"medium_large":false,"large":false,"1536x1536":false,"2048x2048":false,"authorship-box-avatar":false,"authorship-box-related":false},"uagb_author_info":{"display_name":"Nuno Cancelo","author_link":"https:\/\/polarising.com\/techinside\/author\/nuno-cancelo\/"},"uagb_comment_info":0,"uagb_excerpt":"While developing a project, it is not uncommon that the project is divided into several stages. Using Scrum terminology, the project has several sprints in which some predetermined features are delivered, and at the end of the sprint one of these deliverables is the handover, helping to identify what was done within the sprint. Although&hellip;","_links":{"self":[{"href":"https:\/\/polarising.com\/techinside\/wp-json\/wp\/v2\/posts\/42815","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/polarising.com\/techinside\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/polarising.com\/techinside\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/polarising.com\/techinside\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/polarising.com\/techinside\/wp-json\/wp\/v2\/comments?post=42815"}],"version-history":[{"count":4,"href":"https:\/\/polarising.com\/techinside\/wp-json\/wp\/v2\/posts\/42815\/revisions"}],"predecessor-version":[{"id":42976,"href":"https:\/\/polarising.com\/techinside\/wp-json\/wp\/v2\/posts\/42815\/revisions\/42976"}],"wp:attachment":[{"href":"https:\/\/polarising.com\/techinside\/wp-json\/wp\/v2\/media?parent=42815"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/polarising.com\/techinside\/wp-json\/wp\/v2\/categories?post=42815"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/polarising.com\/techinside\/wp-json\/wp\/v2\/tags?post=42815"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}