The code and data behind xeiaso.net
blog/2020: migrate old Palisade post
Signed-off-by: Xe Iaso <me@xeiaso.net>
+157
+157
lume/src/blog/2020/palisade.mdx
+157
lume/src/blog/2020/palisade.mdx
···
1
+
---
2
+
title: "Palisade: Version Bumping at Scale in CI"
3
+
date: 2020-09-14
4
+
---
5
+
6
+
<XeblogConv name="Cadey" mood="enby">
7
+
This post was originally available on the LightspeedHQ Tech blog. That
8
+
blog has since been discontinued. Should you want to read the post in
9
+
its original form, it is available on
10
+
[archive.org](https://web.archive.org/web/20210318102148/https://tech.lightspeedhq.com/palisade-version-bumping-at-scale-in-ci/).
11
+
This version of the post is archived here for posterity.
12
+
</XeblogConv>
13
+
14
+
Traditionally, software release processes are done manually and can be
15
+
difficult to integrate into review processes. At Lightspeed, we
16
+
created [Palisade](https://github.com/lightspeed/palisade) to solve
17
+
this problem. Palisade moves version and release information from
18
+
repository metadata into the repository itself so that is easier to
19
+
review and approve. Palisade is open-source software released under
20
+
the MIT license and can be used by anyone that wants to do version
21
+
bumping as a part of their CI processes.
22
+
23
+
## CHANGELOG.md and VERSION Files
24
+
25
+
Palisade works by reading two files in the root of your repository:
26
+
27
+
* A [`CHANGELOG.md`](https://keepachangelog.com/en/1.0.0/) file that
28
+
describes the changes made to the program
29
+
* A `VERSION` file that contains the current version of the program
30
+
(ideally following [semantic versioning](https://semver.org/))
31
+
32
+
Every time Palisade is run, it will check the git repository for
33
+
version tags based on the contents of the `VERSION` file. If it finds
34
+
that the current version has already been tagged, Palisade will do
35
+
nothing and exit with the exit code 0. If Palisade finds that there is
36
+
a new release, the software will then read the changelog file, scrape
37
+
it for release notes, then use those release notes when creating a new
38
+
release on GitHub.
39
+
40
+
As an example, here is a fragment of [Palisade’s
41
+
changelog](https://github.com/lightspeed/palisade/blob/master/CHANGELOG.md)
42
+
and the release that was created on GitHub:
43
+
44
+
```markdown
45
+
## 0.4.0
46
+
47
+
Tag names were incorrectly generated. Before they were the version
48
+
numbers, but now they are `v${VERSION}`. This should fix compatibility
49
+
issues with Go modules.
50
+
51
+
An end-to-end test has been fixed as well.
52
+
```
53
+
54
+
This changelog fragment was scraped out and used as the release notes
55
+
for [this
56
+
release](https://github.com/lightspeed/palisade/releases/tag/v0.4.0).
57
+
58
+
## Setup
59
+
60
+
There is more up-to-date detail here, but at a high level you need to
61
+
do the following things:
62
+
63
+
* Set up a CHANGELOG.md file
64
+
* Set up a VERSION file
65
+
* Commit these files to your repository
66
+
* Create a GitHub token with the `repo` permission
67
+
* Be sure the user associated with that GitHub token has Maintain
68
+
permissions on the repository
69
+
* Add this token to your CI configuration (use secrets when possible)
70
+
* Add CI configuration
71
+
* Push this all to your repository
72
+
* Test a version bump
73
+
* Sit back and relax
74
+
75
+
### Version Bump Flow
76
+
77
+
To release a new version of a program, first update the version file
78
+
to the desired version. Open the `VERSION` file with your favorite
79
+
text editor and replace:
80
+
81
+
```
82
+
0.1.0
83
+
```
84
+
85
+
with:
86
+
87
+
```
88
+
0.2.0
89
+
```
90
+
91
+
Then, update the changelog file with the changes in that version. For
92
+
example if version `0.2.0` added the ability to interface with clients
93
+
using GraphQL, you could add this to your `CHANGELOG.md`:
94
+
95
+
```markdown
96
+
## 0.2.0
97
+
98
+
### ADDED
99
+
100
+
- Exposed GraphQL API for customers and internal integrators
101
+
102
+
### FIXED
103
+
104
+
- Solved WAT-2392 which previously prevented users from being able to
105
+
refrobnicate already frobnicated strings when using the secret
106
+
management API.
107
+
```
108
+
109
+
When Palisade runs, it will load the contents of the `VERSION` file
110
+
and compare it to the list of git tags in the repo. If that version
111
+
tag is not found, then it will create a new GitHub release with the
112
+
changelog entry for the new version. Palisade will never re-tag
113
+
releases, so it will do nothing if you make a commit without changing
114
+
the current version number.
115
+
116
+
When Palisade processes the above changelog, it would create a release
117
+
for tag `v0.2.0` with the following notes:
118
+
119
+
```markdown
120
+
### ADDED
121
+
122
+
- Exposed GraphQL API for customers and internal integrators
123
+
124
+
### FIXED
125
+
126
+
- Solved WAT-2392 which previously prevented users from being able to
127
+
refrobnicate already frobnicated strings when using the secret
128
+
management API.
129
+
```
130
+
131
+
## Architecture
132
+
133
+
Palisade is written in Rust and uses Nix to build Docker images. Rust
134
+
allowed this project to be developed incredibly quickly and Nix makes
135
+
the built Docker image as small as possible (16 megabytes or so when
136
+
gzipped).
137
+
138
+
One of the biggest problems that came up during development was the
139
+
fact that the existing GitHub API clients were outdated and
140
+
insufficient for our needs. Thanks to the hard work done by the team
141
+
behind reqwest, it was easy for us to create a minimal wrapper around
142
+
the parts of the GitHub API that Palisade requires, and we’ve exposed
143
+
it for reuse. If you want to use this library in your Rust projects,
144
+
add the following to your `Cargo.toml` file:
145
+
146
+
```ini
147
+
[dependencies.github]
148
+
git = "https://github.com/lightspeed/palisade"
149
+
```
150
+
151
+
---
152
+
153
+
To find out more about Palisade, check out its repo at
154
+
[github.com/lightspeed/palisade](https://github.com/lightspeed/palisade).
155
+
We welcome feedback and contributions. If you run into any problems,
156
+
please be sure to let us know and we can help resolve them and correct
157
+
any documentation that leads you down the wrong path.