05019ff2.bdefa62a.js

"use strict";(self.webpackChunkadminforth=self.webpackChunkadminforth||[]).push([[9638],{3469:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>l,contentTitle:()=>r,default:()=>h,frontMatter:()=>a,metadata:()=>i,toc:()=>d});var i=s(411),t=s(4848),o=s(8453);const a={slug:"why-manual-release-notes-and-versions-are-a-chaos-and-how-to-fix-it",title:"Why manual Release Notes and Versions are a chaos and how to fix it",description:"Learn what profits you can get from automatic versioning and learn how simply you can configure it!",authors:"ivanb",tags:["git","versioning","npm"],image:"/ogs/autover.jpg"},r=void 0,l={authorsImageUrls:[void 0]},d=[{value:"Prehistory and issues",id:"prehistory-and-issues",level:2},{value:"What is npm pre-release version?",id:"what-is-npm-pre-release-version",level:3},{value:"Issue one: easy to forget add something to CHANGELOG.md",id:"issue-one-easy-to-forget-add-something-to-changelogmd",level:3},{value:"Issue two: CHANGELOG.md might be forgot to be changed before release as all",id:"issue-two-changelogmd-might-be-forgot-to-be-changed-before-release-as-all",level:3},{value:"Issue three: lack of GitHub releases or need to maintain both",id:"issue-three-lack-of-github-releases-or-need-to-maintain-both",level:3},{value:"Issue four: manual tags",id:"issue-four-manual-tags",level:3},{value:"Issue five: dump commits",id:"issue-five-dump-commits",level:3},{value:"Issue six: releae delay and bus-factor",id:"issue-six-releae-delay-and-bus-factor",level:3},{value:"Issue seven: lack of pre-release versions changes",id:"issue-seven-lack-of-pre-release-versions-changes",level:3},{value:"Semantic-release: what is it and how it works",id:"semantic-release-what-is-it-and-how-it-works",level:2},{value:"Ussage example",id:"ussage-example",level:2},{value:"Connecting to CI",id:"connecting-to-ci",level:2},{value:"Generating GitHub acces token",id:"generating-github-acces-token",level:3},{value:"Generating NPM token",id:"generating-npm-token",level:3},{value:"Testing",id:"testing",level:2},{value:"Next distribution channel",id:"next-distribution-channel",level:3},{value:"Slack notifications about releases",id:"slack-notifications-about-releases",level:2},{value:"Should I maintain CHANGELOG.md anymore?",id:"should-i-maintain-changelogmd-anymore",level:2},{value:"Is it all that good?",id:"is-it-all-that-good",level:2}];function c(e){const n={a:"a",blockquote:"blockquote",code:"code",h2:"h2",h3:"h3",img:"img",li:"li",ol:"ol",p:"p",pre:"pre",ul:"ul",...(0,o.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(n.p,{children:"I have a feeling that after first ~600 versions of Adminforth we faced all possible issues with manual versioning and release notes."}),"\n",(0,t.jsx)(n.p,{children:"Manual versioning and CHANGELOG.md is unreliable as human beings are. It is pretty easy to forget it with relevant information, forget to include some changes, forget to push it to GitHub, push it at wrong time, and many more things."}),"\n",(0,t.jsxs)(n.p,{children:["That is why we decided to move the idea of generating versions, and GitHub releases from git commit messages using great tool called ",(0,t.jsx)(n.a,{href:"https://semantic-release.gitbook.io/semantic-release/usage/configuration",children:"semantic-release"}),"."]}),"\n",(0,t.jsx)(n.p,{children:"In this post I will explain why we did a transition from manual releases to automatic, what profits we got from it, and also will show you simple example how to do it in your project!"}),"\n",(0,t.jsx)(n.h2,{id:"prehistory-and-issues",children:"Prehistory and issues"}),"\n",(0,t.jsx)(n.p,{children:"Before 1.6.0 AdminForth was using manual CHANGELOG.md."}),"\n",(0,t.jsxs)(n.p,{children:["During development we were reviwing PRs, merged them all to ",(0,t.jsx)(n.code,{children:"main"})," branch, pulled to local machine and there did manually npm release which also created a git tag and pushed it to GitHub."]}),"\n",(0,t.jsxs)(n.p,{children:["We were constantly releasing to ",(0,t.jsx)(n.code,{children:"next"})," pre-release version from ",(0,t.jsx)(n.code,{children:"main"})," and used ",(0,t.jsx)(n.code,{children:"next"})," internally on our projets for testing."]}),"\n",(0,t.jsx)(n.h3,{id:"what-is-npm-pre-release-version",children:"What is npm pre-release version?"}),"\n",(0,t.jsx)(n.p,{children:"If you are not familiar with pre-release versions, I can explain it on simple example."}),"\n",(0,t.jsxs)(n.p,{children:["If you have version ",(0,t.jsx)(n.code,{children:"1.2.3"})," in your ",(0,t.jsx)(n.code,{children:"package.json"})," and you run ",(0,t.jsx)(n.code,{children:"npm version patch"})," it will bump version to ",(0,t.jsx)(n.code,{children:"1.2.4"}),". If you run it again it will bump version to ",(0,t.jsx)(n.code,{children:"1.2.5"}),".\nIf you have version ",(0,t.jsx)(n.code,{children:"1.2.3"})," and run ",(0,t.jsx)(n.code,{children:"npm version prerelease --preid=next"})," it will bump version to ",(0,t.jsx)(n.code,{children:"1.2.4-next.0"}),". If you run it again it will bump version to ",(0,t.jsx)(n.code,{children:"1.2.4-next.1"}),". If you run ",(0,t.jsx)(n.code,{children:"npm version patch"})," now it will release version ",(0,t.jsx)(n.code,{children:"1.2.4"}),", hoever if at last step you run ",(0,t.jsx)(n.code,{children:"npm version minor"})," it would release version ",(0,t.jsx)(n.code,{children:"1.3.0"}),"."]}),"\n",(0,t.jsxs)(n.p,{children:["Please pay attention that ",(0,t.jsx)(n.code,{children:"npm"})," is pretty smart and aligned with normal software release cycle \u2013 once you run ",(0,t.jsx)(n.code,{children:"npm version pre-release"})," on stable version, it understands that you start working on new version and will bump patch version. Once you run ",(0,t.jsx)(n.code,{children:"npm version patch"})," at pre-release version, it will release it as stable version without bumping patch number."]}),"\n",(0,t.jsxs)(n.p,{children:["This is very useful because we can collect features and fixes in ",(0,t.jsx)(n.code,{children:"next"})," version without releasing them to ",(0,t.jsx)(n.code,{children:"latest"})," version, so users who do ",(0,t.jsx)(n.code,{children:"npm install adminforth"})," will not get new experimental features and fixes, but thouse who want to test them early can do ",(0,t.jsx)(n.code,{children:"npm install adminforth@next"}),". Our team also using ",(0,t.jsx)(n.code,{children:"next"})," for commercial projects to test new features so in the end of the day we have more stable ",(0,t.jsx)(n.code,{children:"latest"})," version."]}),"\n",(0,t.jsx)(n.p,{children:"In new automatic release process we preserved this approach, but made it in separate git branches."}),"\n",(0,t.jsxs)(n.p,{children:["Once we collected enough features and fixes in ",(0,t.jsx)(n.code,{children:"next"}),", we were doing a release to ",(0,t.jsx)(n.code,{children:"latest"})," version, and at this time we did release documentation."]}),"\n",(0,t.jsx)(n.h3,{id:"issue-one-easy-to-forget-add-something-to-changelogmd",children:"Issue one: easy to forget add something to CHANGELOG.md"}),"\n",(0,t.jsxs)(n.p,{children:["So when I merged PRs to ",(0,t.jsx)(n.code,{children:"main"})," branch, I had to check commits and write them to CHANGELOG.md."]}),"\n",(0,t.jsxs)(n.p,{children:["At this point I wasted time to understand how to call the change in CHANGELOG.md, and categorize it as ",(0,t.jsx)(n.code,{children:"Added"}),", ",(0,t.jsx)(n.code,{children:"Changed"}),", ",(0,t.jsx)(n.code,{children:"Fixed"}),", ",(0,t.jsx)(n.code,{children:"Removed"}),", ",(0,t.jsx)(n.code,{children:"Security"}),"."]}),"\n",(0,t.jsx)(n.p,{children:"Also there was a chance that I will skip some commit, or will understand wrong what it was about."}),"\n",(0,t.jsx)(n.h3,{id:"issue-two-changelogmd-might-be-forgot-to-be-changed-before-release-as-all",children:"Issue two: CHANGELOG.md might be forgot to be changed before release as all"}),"\n",(0,t.jsxs)(n.p,{children:["There was a chance that I will forget to update ",(0,t.jsx)(n.code,{children:"CHANGELOG.md"})," at all. I merged PRs, I am hurry and doing release."]}),"\n",(0,t.jsx)(n.p,{children:'Sometimes I will soon understand that I forgot to update it and will push it to GitHub. It will born another dump commit message like "Update a CHANGELOG.md".'}),"\n",(0,t.jsxs)(n.p,{children:["Also I am not sure that users are looking into ",(0,t.jsx)(n.code,{children:"main"})," branch to see CHANGELOG, probably they see it in npmjs.com."]}),"\n",(0,t.jsx)(n.h3,{id:"issue-three-lack-of-github-releases-or-need-to-maintain-both",children:"Issue three: lack of GitHub releases or need to maintain both"}),"\n",(0,t.jsx)(n.p,{children:"We did not have GitHub releases at all at that time. We had only tags. And tags were applied only after release."}),"\n",(0,t.jsx)(n.p,{children:"But honestly, when I am by myself working with some pacakge, first try to find GitHub releases, though CHANGELOG.md."}),"\n",(0,t.jsx)(n.p,{children:"So if I would add GitHub releases, I would have to do a lot of clicks or would need some script / CLI to create release notes. This process would have similar issues as with CHANGELOG.md."}),"\n",(0,t.jsx)(n.h3,{id:"issue-four-manual-tags",children:"Issue four: manual tags"}),"\n",(0,t.jsx)(n.p,{children:"Since release was manual from my PC there was a chance that I will do some minor fix, will forget to commit it, then will do release and release script will add tag to previous, irrelevant commit."}),"\n",(0,t.jsxs)(n.p,{children:["In such projects with manual tags, there is only one reliabile way for package user to to check what is difference in source code between two versions: using some tool like ",(0,t.jsx)(n.a,{href:"https://npmdiff.dev/",children:"https://npmdiff.dev/"})," and not rely on git and CHANGELOG"]}),"\n",(0,t.jsx)(n.p,{children:"Since git tags were applied only after release and there again was a chance that I will forget to push them to GitHub with a release."}),"\n",(0,t.jsx)(n.h3,{id:"issue-five-dump-commits",children:"Issue five: dump commits"}),"\n",(0,t.jsxs)(n.p,{children:["Since with every manual release we updated CHANGELOG.md and updated version in ",(0,t.jsx)(n.code,{children:"pacakge.json"})," every time, we had to do a commit."]}),"\n",(0,t.jsx)(n.p,{children:'So it borned a lot of dump commits like "Update CHANGELOG.md", "Update version to 1.2.3", "Update version to 1.2.4", "Update version to 1.2.5".'}),"\n",(0,t.jsx)(n.p,{children:"Sometime it wass forgot to be commited separately and was commited with other changes in some fix which is even worsen."}),"\n",(0,t.jsx)(n.h3,{id:"issue-six-releae-delay-and-bus-factor",children:"Issue six: releae delay and bus-factor"}),"\n",(0,t.jsx)(n.p,{children:"So if I was busy new features were waiting for release, becuase only I had access to do releases."}),"\n",(0,t.jsx)(n.p,{children:"Sonner I passed access to some of my colleagues to do releases but from time to time it caused state desync and release issues between our PCs if someone forgot to push something to GitHub after release."}),"\n",(0,t.jsx)(n.p,{children:"Even couple of release contrubuters are onboard, it still takes a time to do all the stuff with Changelog, version, tags, etc, so it delays release."}),"\n",(0,t.jsx)(n.h3,{id:"issue-seven-lack-of-pre-release-versions-changes",children:"Issue seven: lack of pre-release versions changes"}),"\n",(0,t.jsxs)(n.p,{children:["While we releasing to ",(0,t.jsx)(n.code,{children:"next"})," we added items under one version in CHANGELOG for simplicity. It would be another extra time to add every ",(0,t.jsx)(n.code,{children:"next"})," version in CHANGELOG and describe whole markdown for it."]}),"\n",(0,t.jsxs)(n.p,{children:["So user was not able to distinguish ",(0,t.jsx)(n.code,{children:"1.5.0-next.0"})," from ",(0,t.jsx)(n.code,{children:"1.5.0-next.1"})," in CHANGELOG, which was not an issue for ",(0,t.jsx)(n.code,{children:"latest"})," users but issue for ",(0,t.jsx)(n.code,{children:"next"})," users."]}),"\n",(0,t.jsx)(n.h2,{id:"semantic-release-what-is-it-and-how-it-works",children:"Semantic-release: what is it and how it works"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.code,{children:"semantic-release"})," is a tool that solved all issues above. Basically it is a CLI tool that you run on your CI/CD server on every push to your repository."]}),"\n",(0,t.jsx)(n.p,{children:"So on every push it analyzes commit messages from previous release and does next things:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["It understands what type of release it should do: major, minor, patch, pre-release depending on commit messages. E.g. if you have a commit message ",(0,t.jsx)(n.code,{children:"feat: add new feature"})," it will do a minor release, if you have ",(0,t.jsx)(n.code,{children:"fix: fix bug"})," it will do a patch release."]}),"\n",(0,t.jsxs)(n.li,{children:["It reads previous version from git tags and does a new version based on type of release. So it does not edit ",(0,t.jsx)(n.code,{children:"package.json"})," file."]}),"\n",(0,t.jsx)(n.li,{children:"It generates a GitHub tag and release notes based on commit messages. So you do not need to write CHANGELOG.md anymore."}),"\n",(0,t.jsxs)(n.li,{children:["It publishes a new version to npmjs.com. So you do not need to do ",(0,t.jsx)(n.code,{children:"npm publish"})," anymore."]}),"\n",(0,t.jsxs)(n.li,{children:["It is capable to release to ",(0,t.jsx)(n.code,{children:"next"})," channel from separate ",(0,t.jsx)(n.code,{children:"next"})," branch without version bumping. So you can collect features and fixes in ",(0,t.jsx)(n.code,{children:"next"})," without releasing them to ",(0,t.jsx)(n.code,{children:"latest"}),"."]}),"\n",(0,t.jsx)(n.li,{children:"It has plugins, for example to send Slack notifications about releases."}),"\n"]}),"\n",(0,t.jsx)(n.p,{children:"The sweet thing that it is all executed on CI/CD server, so you do not need to do anything manually."}),"\n",(0,t.jsx)(n.h2,{id:"ussage-example",children:"Ussage example"}),"\n",(0,t.jsx)(n.p,{children:"I will show a flow on empty fake small project to not overcomplicate things."}),"\n",(0,t.jsx)(n.p,{children:"This will allow you to apply it to your project once you ready."}),"\n",(0,t.jsxs)(n.p,{children:["We will use minimal typescript package with ",(0,t.jsx)(n.code,{children:"npm"})," and ",(0,t.jsx)(n.code,{children:"semantic-release"})," to show how it works."]}),"\n",(0,t.jsx)(n.p,{children:"First init new git repository:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:'echo "# test-sem-release" >> README.md\ngit init\ngit add README.md\ngit commit -m "first commit"\ngit branch -M main\ngit remote add origin git@github.com:devforth/test-sem-release.git\ngit push -u origin main\n'})}),"\n",(0,t.jsxs)(n.p,{children:["Now lets init new ",(0,t.jsx)(n.code,{children:"npm package"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"npm init -y\nnpm install typescript --save-dev\nnpx tsc --init\n"})}),"\n",(0,t.jsxs)(n.p,{children:["Create a file ",(0,t.jsx)(n.code,{children:"index.ts"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",metastring:'title="index.ts"',children:"export const greet = (name: string): string => {\n  return `Hello, ${name}!`;\n};\n"})}),"\n",(0,t.jsxs)(n.p,{children:["In ",(0,t.jsx)(n.code,{children:"package.json"})," add:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n  "name": "@devforth/test-sem-release",\n//diff-add\n  "publishConfig": {\n//diff-add\n    "access": "public"\n//diff-add\n  },\n  "version": "1.0.0",\n  "main": "index.js",\n  "scripts": {\n    "test": "echo \\"Error: no test specified\\" && exit 1"\n//diff-add\n    "build": "tsc",\n  },\n  "author": "",\n  "license": "ISC",\n  "description": "",\n//diff-add\n  "release": {\n//diff-add\n    "branches": [\n//diff-add\n      "main",\n//diff-add\n      {\n//diff-add\n        "name": "next",\n//diff-add\n        "prerelease": true\n//diff-add\n      }\n//diff-add\n    ],\n//diff-add\n    "plugins": [\n//diff-add\n      "@semantic-release/commit-analyzer",\n//diff-add\n      "@semantic-release/release-notes-generator",\n//diff-add\n      "@semantic-release/npm",\n//diff-add\n      "@semantic-release/github"\n//diff-add\n    ],\n//diff-add\n  }\n}\n'})}),"\n",(0,t.jsxs)(n.p,{children:["Make sure name in ",(0,t.jsx)(n.code,{children:"package.json"})," has your organisation name like mine ",(0,t.jsx)(n.code,{children:"@devforth/"})," and you have access to publish packages to npmjs.com."]}),"\n",(0,t.jsxs)(n.p,{children:["Also install ",(0,t.jsx)(n.code,{children:"semantic-release"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"npm i -D semantic-release\n"})}),"\n",(0,t.jsx)(n.h2,{id:"connecting-to-ci",children:"Connecting to CI"}),"\n",(0,t.jsxs)(n.p,{children:["We will use Woodpecker CI for this example. Woodpecker is a free and open-source CI/CD tool that you can install to your own server / VPS and will not need to pay for build minutes, and will only for server. No limits on pipelines, users, repositories, etc. If you want to try it, we have ",(0,t.jsx)(n.a,{href:"https://devforth.io/blog/step-by-step-guide-to-modern-secure-ci-setup/",children:"Woodpecker installation guide"})]}),"\n",(0,t.jsxs)(n.p,{children:["Create a file ",(0,t.jsx)(n.code,{children:".woodpecker.yml"})," in ",(0,t.jsx)(n.code,{children:"deploy"})," directory:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yml",metastring:'title="deploy/.woodpecker.yml"',children:"clone:\n  git:\n    image: woodpeckerci/plugin-git\n    settings:\n      partial: false\n      depth: 5\n\nsteps:\n  release:\n    image: node:22\n    when:\n      - event: push\n    commands:\n      - npm clean-install\n      - npm run build\n      - npm audit signatures\n      - npx semantic-release\n    secrets:\n      - GITHUB_TOKEN\n      - NPM_TOKEN\n"})}),"\n",(0,t.jsxs)(n.p,{children:["Go to Woodpecker, authorize via GitHub, click ",(0,t.jsx)(n.code,{children:"Add repository"}),", find your repository and add it."]}),"\n",(0,t.jsxs)(n.p,{children:["Disable ",(0,t.jsx)(n.code,{children:"Project settings"})," -> ",(0,t.jsx)(n.code,{children:"Allow Pull Requests"})," because we do not want to trigger builds on PRs.\nEnable ",(0,t.jsx)(n.code,{children:"Project settings"})," -> ",(0,t.jsx)(n.code,{children:"Trusted"}),"\nEnable ",(0,t.jsx)(n.code,{children:"Project Visibility"})," -> ",(0,t.jsx)(n.code,{children:"Internal"})," unless you want to make it public."]}),"\n",(0,t.jsxs)(n.blockquote,{children:["\n",(0,t.jsxs)(n.p,{children:["We strictly recommend to use ",(0,t.jsx)(n.code,{children:"Internal"})," visibility for your projects, because if you use ",(0,t.jsx)(n.code,{children:"Public"})," visibility, your build logs will be public and if accidentally you will print some secret to console, it will be public (generally it happens when you debug something and print environment variables)."]}),"\n"]}),"\n",(0,t.jsx)(n.p,{children:(0,t.jsx)(n.img,{alt:"Woodpecker project settings",src:s(5047).A+"",width:"2443",height:"1799"})}),"\n",(0,t.jsx)(n.h3,{id:"generating-github-acces-token",children:"Generating GitHub acces token"}),"\n",(0,t.jsx)(n.p,{children:"If your repo is in GitHub organisation, you need first enable access to personal access tokens for your organisation (if not yet done):"}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["In the upper-right corner of GitHub, select your profile photo, then click ",(0,t.jsx)(n.code,{children:"Your organizations"}),"."]}),"\n",(0,t.jsxs)(n.li,{children:["Next to the organization, click ",(0,t.jsx)(n.code,{children:"Settings"}),"."]}),"\n",(0,t.jsxs)(n.li,{children:["In the left sidebar, under  Personal access tokens, click ",(0,t.jsx)(n.code,{children:"Settings"}),"."]}),"\n",(0,t.jsxs)(n.li,{children:["Select ",(0,t.jsx)(n.code,{children:"Allow access via fine-grained personal access tokens"})]}),"\n",(0,t.jsxs)(n.li,{children:["We recommend setting ",(0,t.jsx)(n.code,{children:"Require administrator approval"})]}),"\n",(0,t.jsx)(n.li,{children:'"Allow access via personal access tokens (classic)"'}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:["Now go to your profile, click on ",(0,t.jsx)(n.code,{children:"Settings"})," -> ",(0,t.jsx)(n.code,{children:"Developer settings"})," -> ",(0,t.jsx)(n.code,{children:"Personal access tokens"})," -> ",(0,t.jsx)(n.code,{children:"Generate new token"})]}),"\n",(0,t.jsx)(n.p,{children:"For permissions,"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Select ",(0,t.jsx)(n.code,{children:"Contents"}),": ",(0,t.jsx)(n.code,{children:"Read and Write"})]}),"\n",(0,t.jsxs)(n.li,{children:["Select ",(0,t.jsx)(n.code,{children:"Metadata"}),": ",(0,t.jsx)(n.code,{children:"Read-only"})," (if not yet selected)"]}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:["In Woodpecker go to ",(0,t.jsx)(n.code,{children:"Settings"}),", ",(0,t.jsx)(n.code,{children:"Secrets"}),", ",(0,t.jsx)(n.code,{children:"Add Secret"}),", put name name: ",(0,t.jsx)(n.code,{children:"GITHUB_TOKEN"})," and paste your token:"]}),"\n",(0,t.jsx)(n.p,{children:(0,t.jsx)(n.img,{alt:"Woodpecker Secrets",src:s(4548).A+"",width:"3447",height:"1796"})}),"\n",(0,t.jsxs)(n.p,{children:["In ",(0,t.jsx)(n.code,{children:"Available at following events"})," select ",(0,t.jsx)(n.code,{children:"Push"}),"."]}),"\n",(0,t.jsx)(n.h3,{id:"generating-npm-token",children:"Generating NPM token"}),"\n",(0,t.jsxs)(n.p,{children:["Go to your npmjs.com account, click on ",(0,t.jsx)(n.code,{children:"Profile Avatar"})," -> ",(0,t.jsx)(n.code,{children:"Access Tokens"})," -> ",(0,t.jsx)(n.code,{children:"Generate New Token"})," -> ",(0,t.jsx)(n.code,{children:"New Granular Access Token"}),"."]}),"\n",(0,t.jsx)(n.p,{children:"Packages and scopes Permissions: Read and Write."}),"\n",(0,t.jsxs)(n.p,{children:["In similar way to GitHub token, add it to Woodpecker as secret with name ",(0,t.jsx)(n.code,{children:"NPM_TOKEN"})]}),"\n",(0,t.jsx)(n.h2,{id:"testing",children:"Testing"}),"\n",(0,t.jsx)(n.p,{children:"For now we did not yet push anything to GitHub and did not publish anything to npm."}),"\n",(0,t.jsx)(n.p,{children:"Lets do it now."}),"\n",(0,t.jsx)(n.p,{children:"Just push your first commit as:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-sh",children:"feat: initial commit\n"})}),"\n",(0,t.jsxs)(n.p,{children:["This will trigger semantic-release to do first release ",(0,t.jsx)(n.code,{children:"v1.0.0"}),"."]}),"\n",(0,t.jsx)(n.p,{children:"Now change something is index.ts and push it as fix"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-sh",children:"fix: fix greet function\n"})}),"\n",(0,t.jsxs)(n.p,{children:["This will trigger semantic-release to do release ",(0,t.jsx)(n.code,{children:"v1.0.1"}),"."]}),"\n",(0,t.jsxs)(n.p,{children:["Now change something in ",(0,t.jsx)(n.code,{children:"index.ts"})," and push it as feat"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-sh",children:"feat: add new function\n"})}),"\n",(0,t.jsxs)(n.p,{children:["This will trigger semantic-release to do release ",(0,t.jsx)(n.code,{children:"v1.1.0"})," because we added new feature, not just fixed something."]}),"\n",(0,t.jsx)(n.h3,{id:"next-distribution-channel",children:"Next distribution channel"}),"\n",(0,t.jsxs)(n.p,{children:["Now we will show how to release to ",(0,t.jsx)(n.code,{children:"next"})," channel."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-sh",children:"git checkout -b next\n"})}),"\n",(0,t.jsx)(n.p,{children:"Change something and push it as fix"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-sh",children:"fix: fix greet function in next\n"})}),"\n",(0,t.jsx)(n.p,{children:"Commit it and push:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-sh",children:"git push --set-upstream origin next\n"})}),"\n",(0,t.jsxs)(n.p,{children:["This will trigger semantic-release to do release ",(0,t.jsx)(n.code,{children:"v1.1.1-next.1"}),". Please not that it bumped patch version because we are in ",(0,t.jsx)(n.code,{children:"next"})," channel."]}),"\n",(0,t.jsx)(n.p,{children:"Now lets add feature to next"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{children:"feat: add new feature in next\n"})}),"\n",(0,t.jsxs)(n.p,{children:["It will trigger release ",(0,t.jsx)(n.code,{children:"v1.2.0-next.1"})," because we added new feature and minor version was bumped. Please not that next number started from 1 again."]}),"\n",(0,t.jsxs)(n.p,{children:["Noe lets merge ",(0,t.jsx)(n.code,{children:"next"})," to ",(0,t.jsx)(n.code,{children:"main"})," and push it:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{children:"git checkout main\ngit merge next\ngit push\n"})}),"\n",(0,t.jsxs)(n.p,{children:["This will trigger release ",(0,t.jsx)(n.code,{children:"v1.2.0"})," because we merged ",(0,t.jsx)(n.code,{children:"next"})," to ",(0,t.jsx)(n.code,{children:"main"})," and it was a feature release."]}),"\n",(0,t.jsx)(n.h2,{id:"slack-notifications-about-releases",children:"Slack notifications about releases"}),"\n",(0,t.jsx)(n.p,{children:"So now we have automatic releases with release notes on GitHub.\nFor our internal team we use Slack and we want to get notifications about releases there."}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-sh",children:"npm i -D semantic-release-slack-bot\n"})}),"\n",(0,t.jsxs)(n.p,{children:['Into "release" section of ',(0,t.jsx)(n.code,{children:"package.json"})," add slack plugin:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:' "plugins": [\n      "@semantic-release/commit-analyzer",\n      "@semantic-release/release-notes-generator",\n      "@semantic-release/npm",\n      "@semantic-release/github",\n//diff-add\n      [\n//diff-add\n        "semantic-release-slack-bot",\n//diff-add\n        {\n//diff-add\n          "notifyOnSuccess": true,\n//diff-add\n          "notifyOnFail": true,\n//diff-add\n          "slackIcon": ":package:",\n//diff-add\n          "markdownReleaseNotes": true\n//diff-add\n        }\n//diff-add\n      ]\n//diff-add\n    ],\n'})}),"\n",(0,t.jsxs)(n.p,{children:["Also create channel in Slack, click on channel name, go to ",(0,t.jsx)(n.code,{children:"Integrations"})," -> ",(0,t.jsx)(n.code,{children:"Add an App"})," -> ",(0,t.jsx)(n.code,{children:"Incoming Webhooks"})," -> ",(0,t.jsx)(n.code,{children:"Add to Slack"}),' -> "Add Incoming Webhook to Workspace" -> "Add to Slack" -> "Copy Webhook URL"']}),"\n",(0,t.jsxs)(n.p,{children:["Add it to Woodpecker as secret ",(0,t.jsx)(n.code,{children:"SLACK_WEBHOOK"})," environment variable."]}),"\n",(0,t.jsxs)(n.p,{children:["Also add this secterd to ",(0,t.jsx)(n.code,{children:".woodpecker.yml"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-yml",metastring:'title="deploy/.woodpecker.yml"',children:"    secrets:\n      - GITHUB_TOKEN\n      - NPM_TOKEN\n//diff-add\n      - SLACK_WEBHOOK\n"})}),"\n",(0,t.jsxs)(n.p,{children:["This will send notifications to Slack channel about succesfull releases when ",(0,t.jsx)(n.code,{children:"npm run build"})," is done without errors:"]}),"\n",(0,t.jsx)(n.p,{children:(0,t.jsx)(n.img,{alt:"Slack notifications about releases",src:s(5678).A+"",width:"1645",height:"711"})}),"\n",(0,t.jsx)(n.h2,{id:"should-i-maintain-changelogmd-anymore",children:"Should I maintain CHANGELOG.md anymore?"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.code,{children:"semantic-release"})," has a plugin for generating not only GitHub release notes, but also CHANGELOG.md."]}),"\n",(0,t.jsxs)(n.p,{children:["Since previusly we used CHANGELOG.md I thought it would be good to have it in project. But once I entered ",(0,t.jsx)(n.a,{href:"https://github.com/semantic-release/changelog",children:"plugin page"})," I got a notice which ",(0,t.jsx)(n.a,{href:"https://semantic-release.gitbook.io/semantic-release/support/faq#should-release-notes-be-committed-to-a-changelog.md-in-my-repository-during-a-release",children:"explained complexity"})," added for this approach."]}),"\n",(0,t.jsxs)(n.p,{children:["So we ended with a simple ",(0,t.jsx)(n.a,{href:"https://github.com/devforth/adminforth/blob/main/CHANGELOG.md",children:"link to GitHub releases"})]}),"\n",(0,t.jsx)(n.h2,{id:"is-it-all-that-good",children:"Is it all that good?"}),"\n",(0,t.jsx)(n.p,{children:"Well, there are no perfect approaches in the world."}),"\n",(0,t.jsxs)(n.p,{children:["Of course ",(0,t.jsx)(n.code,{children:"semantic-release"})," has some cons."]}),"\n",(0,t.jsx)(n.p,{children:"First of all, while you can write a commit messages without any prefix and they will not be included in release, you still have to follow strict commit message format when you are releasing feature or fix. And you don't have to forget to use this format. Instead of making manual forming of release notes which is done by one person, now every developer in team has to follow the same format and has to write clear commit messages."}),"\n",(0,t.jsx)(n.p,{children:"And there are couple of bad things with last points:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"It is not so easy to modify commit message once it is pushed to GitHub, so commit writing becomes one of the most critical parts of development process where you have to be very careful."}),"\n",(0,t.jsx)(n.li,{children:"Commit message should be understood not only by developers of framework, but also by users of framework. And some developers might think that these are two absolutely different dementions of understanding: first one is for developers, second one is for users. But in fact, at AdminForth, we think that set of user-friendly commit messages is a very small subset of set of developer-friendly commit messages. So if you write user-friendly commit messages, there is no chance that developers will not understand them."}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:["You are still fine with merging incoming PRs and ignore their commit messages becuse GitHub allows to edit commit message before merging ( using ",(0,t.jsx)(n.code,{children:"Squash and merge"})," option )"]})]})}function h(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(c,{...e})}):c(e)}},5047:(e,n,s)=>{s.d(n,{A:()=>i});const i=s.p+"assets/images/image-4-10736f83a40640d8963b0dd68fb3e759.png"},5678:(e,n,s)=>{s.d(n,{A:()=>i});const i=s.p+"assets/images/image-5-ec5a52db880a586bef36f2987d319596.png"},4548:(e,n,s)=>{s.d(n,{A:()=>i});const i=s.p+"assets/images/image-64910662d2872a85b76892870c2ab222.png"},8453:(e,n,s)=>{s.d(n,{R:()=>a,x:()=>r});var i=s(6540);const t={},o=i.createContext(t);function a(e){const n=i.useContext(o);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function r(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:a(e.components),i.createElement(o.Provider,{value:n},e.children)}},411:e=>{e.exports=JSON.parse('{"permalink":"/blog/why-manual-release-notes-and-versions-are-a-chaos-and-how-to-fix-it","source":"@site/blog/2025-01-19-how-adminforth-manages-version/index.md","title":"Why manual Release Notes and Versions are a chaos and how to fix it","description":"Learn what profits you can get from automatic versioning and learn how simply you can configure it!","date":"2025-01-19T00:00:00.000Z","tags":[{"inline":false,"label":"Git","permalink":"/blog/tags/git","description":"Git is a distributed version control system that allows multiple developers to collaborate on a project."},{"inline":false,"label":"Versioning","permalink":"/blog/tags/versioning","description":"Versioning is the process of assigning unique identifiers to different versions of a software application or project."},{"inline":false,"label":"NPM","permalink":"/blog/tags/npm","description":"NPM is a package manager for the JavaScript programming language that allows developers to share and reuse code."}],"readingTime":13.12,"hasTruncateMarker":true,"authors":[{"name":"Ivan Borshchov","title":"Maintainer of AdminForth","url":"https://github.com/ivictbor","imageURL":"https://avatars.githubusercontent.com/u/1838656?v=4","key":"ivanb","page":null}],"frontMatter":{"slug":"why-manual-release-notes-and-versions-are-a-chaos-and-how-to-fix-it","title":"Why manual Release Notes and Versions are a chaos and how to fix it","description":"Learn what profits you can get from automatic versioning and learn how simply you can configure it!","authors":"ivanb","tags":["git","versioning","npm"],"image":"/ogs/autover.jpg"},"unlisted":false,"prevItem":{"title":"How I Open-Sourced My Secret Access Tokens from GitHub, Slack, and NPM \u2014 and Who Actually Cares","permalink":"/blog/how-i-opensourced-my-secret-tokens"},"nextItem":{"title":"Backup database to AWS Glacier","permalink":"/blog/backup-database-to-aws-glacier"}}')}}]);