You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: Why manual Release Notes and Versions are a chaos and how to fix it
4
4
description: Learn what profits you can get from automatic versioning and learn how simply you can configure it!
5
5
authors: ivanb
6
-
tags: [git, versioning]
6
+
tags: [git, versioning, npm]
7
+
image: "/ogs/autover.jpg"
7
8
---
8
9
9
10
I have a feeling that after first ~600 versions of Adminforth we faced all possible issues with manual versioning and release notes.
@@ -29,70 +30,70 @@ If you are not familiar with pre-release versions, I can explain it on simple ex
29
30
If you have version `1.2.3` in your `package.json` and you run `npm version patch` it will bump version to `1.2.4`. If you run it again it will bump version to `1.2.5`.
30
31
If you have version `1.2.3` and run `npm version prerelease --preid=next` it will bump version to `1.2.4-next.0`. If you run it again it will bump version to `1.2.4-next.1`. If you run `npm version patch` now it will release version `1.2.4`, hoever if at last step you run `npm version minor` it would release version `1.3.0`.
31
32
32
-
Please pay attention that `npm` is pretty smart and aligned with normal software release cycle -- once you run `npm version pre-release` on stable version, it understands that you start working on new version and will bump patch version. Once you run `npm version patch` at pre-release version, it will release it as stable version without bumping patch number.
33
+
Please pay attention that `npm` is pretty smart and aligned with normal software release cycle – once you run `npm version pre-release` on stable version, it understands that you start working on new version and will bump patch version. Once you run `npm version patch` at pre-release version, it will release it as stable version without bumping patch number.
33
34
34
35
This is very useful because we can collect features and fixes in `next` version without releasing them to `latest` version, so users who do `npm install adminforth` will not get new experimental features and fixes, but thouse who want to test them early can do `npm install adminforth@next`. Our team also using `next` for commercial projects to test new features so in the end of the day we have more stable `latest` version.
35
36
36
37
In new automatic release process we preserved this approach, but made it in separate git branches.
37
38
38
39
Once we collected enough features and fixes in `next`, we were doing a release to `latest` version, and at this time we did release documentation.
39
40
40
-
### Issue one -- easy to forget add something to CHANGELOG.md
41
+
### Issue one: easy to forget add something to CHANGELOG.md
41
42
42
43
So when I merged PRs to `main` branch, I had to check commits and write them to CHANGELOG.md.
43
44
44
45
At this point I wasted time to understand how to call the change in CHANGELOG.md, and categorize it as `Added`, `Changed`, `Fixed`, `Removed`, `Security`.
45
46
46
47
Also there was a chance that I will skip some commit, or will understand wrong what it was about.
47
48
48
-
### Issue two -- CHANGELOG.md might be forgot to be changed before release as all
49
+
### Issue two: CHANGELOG.md might be forgot to be changed before release as all
49
50
50
51
There was a chance that I will forget to update `CHANGELOG.md` at all. I merged PRs, I am hurry and doing release.
51
52
52
53
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".
53
54
54
55
Also I am not sure that users are looking into `main` branch to see CHANGELOG, probably they see it in npmjs.com.
55
56
56
-
### Issue three -- lack of GitHub releases or need to maintain both
57
+
### Issue three: lack of GitHub releases or need to maintain both
57
58
58
59
We did not have GitHub releases at all at that time. We had only tags. And tags were applied only after release.
59
60
60
61
But honestly, when I am by myself working with some pacakge, first try to find GitHub releases, though CHANGELOG.md.
61
62
62
63
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.
63
64
64
-
### Issue four -- manual tags
65
+
### Issue four: manual tags
65
66
66
67
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.
67
68
68
69
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 https://npmdiff.dev/ and not rely on git and CHANGELOG
69
70
70
71
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.
71
72
72
-
### Issue five -- dump commits
73
+
### Issue five: dump commits
73
74
74
75
Since with every manual release we updated CHANGELOG.md and updated version in `pacakge.json` every time, we had to do a commit.
75
76
76
77
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".
77
78
78
79
Sometime it wass forgot to be commited separately and was commited with other changes in some fix which is even worsen.
79
80
80
-
### Issue six -- releae delay and bus-factor
81
+
### Issue six: releae delay and bus-factor
81
82
82
83
So if I was busy new features were waiting for release, becuase only I had access to do releases.
83
84
84
85
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.
85
86
86
87
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.
87
88
88
-
### Issue seven -- lack of pre-release versions changes
89
+
### Issue seven: lack of pre-release versions changes
89
90
90
91
While we releasing to `next` we added items under one version in CHANGELOG for simplicity. It would be another extra time to add every `next` version in CHANGELOG and describe whole markdown for it.
91
92
92
93
So user was not able to distinguish `1.5.0-next.0` from `1.5.0-next.1` in CHANGELOG, which was not an issue for `latest` users but issue for `next` users.
93
94
94
95
95
-
## Semantic-release -- what is it and how it works
96
+
## Semantic-release: what is it and how it works
96
97
97
98
`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.
98
99
@@ -215,7 +216,7 @@ We will use Woodpecker CI for this example. Woodpecker is a free and open-source
215
216
216
217
Create a file `.woodpecker.yml` in `deploy` directory:
217
218
218
-
```yaml title="deploy/.woodpecker.yml"
219
+
```yml title="deploy/.woodpecker.yml"
219
220
clone:
220
221
git:
221
222
image: woodpeckerci/plugin-git
@@ -368,7 +369,7 @@ npm i -D semantic-release-slack-bot
368
369
369
370
Into "release" section of `package.json` add slack plugin:
370
371
371
-
```
372
+
```json
372
373
"plugins": [
373
374
"@semantic-release/commit-analyzer",
374
375
"@semantic-release/release-notes-generator",
@@ -403,7 +404,7 @@ Add it to Woodpecker as secret `SLACK_WEBHOOK` environment variable.
403
404
404
405
Also add this secterd to `.woodpecker.yml`:
405
406
406
-
```yaml title="deploy/.woodpecker.yml"
407
+
```yml title="deploy/.woodpecker.yml"
407
408
secrets:
408
409
- GITHUB_TOKEN
409
410
- NPM_TOKEN
@@ -425,3 +426,17 @@ Since previusly we used CHANGELOG.md I thought it would be good to have it in pr
425
426
426
427
So we ended with a simple [link to GitHub releases](https://github.com/devforth/adminforth/blob/main/CHANGELOG.md)
427
428
429
+
## Is it all that good?
430
+
431
+
Well, there are no perfect approaches in the world.
432
+
433
+
Of course `semantic-release` has some cons.
434
+
435
+
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.
436
+
437
+
And there are couple of bad things with last points:
438
+
- 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.
439
+
- 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.
440
+
441
+
442
+
You are still fine with merging incoming PRs and ignore their commit messages becuse GitHub allows to edit commit message before merging ( using `Squash and merge` option )
0 commit comments