mirror of
https://github.com/iv-org/documentation.git
synced 2025-05-21 16:10:36 -04:00
125 lines
3.4 KiB
Markdown
125 lines
3.4 KiB
Markdown
# How to make a new Invidious release
|
||
|
||
## Preamble
|
||
|
||
In the following document, `vX.Y.Z` is the release version, which should follow
|
||
the pattern `v<MAJOR>.<YYYY><MM><DD>.<PATCH>`
|
||
|
||
The major component is only updated on breaking changes (database migrations,
|
||
incompatible config changes). The minor component is the current UTC date.
|
||
The patch component is updated if a second release is done the same day.
|
||
|
||
|
||
## Step 0
|
||
|
||
Make sure you're synced with upstream:
|
||
```sh
|
||
git checkout master
|
||
git remote update
|
||
git pull origin master
|
||
```
|
||
|
||
## Step 1
|
||
|
||
* Update version in `shard.yml`.
|
||
* Update `CHANGELOG.md` to reflect the changes made since the last release.
|
||
|
||
Each changelog entry is composed of a summary and a list of PRs.
|
||
|
||
The summary should be simple and concise, and only reflect most important
|
||
changes, preferably sorted by impact (new features/breaking changes that the
|
||
users will see goes first, changes that affect developers/API users should go
|
||
last). Minor changes that are related to repo maintenance can be ignored.
|
||
|
||
Do not forget to list **ALL** the PRs that have been merged since the last
|
||
release, with the proper links.
|
||
|
||
Note: Maybe this should be done each time a PR is merged?
|
||
|
||
|
||
## Step 2
|
||
|
||
Commit the changes made in step 1:
|
||
```sh
|
||
git add CHANGELOG.md shard.yml
|
||
git commit -S -m "Release vX.Y.Z"
|
||
```
|
||
|
||
**THEN** tag your release, like so:
|
||
```sh
|
||
git tag -as vX.Y.Z
|
||
```
|
||
|
||
Git will ask to provide a tag annotation. All you have to do is copy/pasting
|
||
the summary from `CHANGELOG.md` and adapt the formatting as required. Do not
|
||
include the list of PRs merged.
|
||
|
||
??? warning Amending your release commit
|
||
|
||
If for some reason you need to amend your release commit (e.g you made a typo
|
||
in the changelog), **make sure to retag afterwards!**
|
||
|
||
Amending a commit will change its hash, but the tag will remain attached to
|
||
the previous (now dangling) commit.
|
||
|
||
Here's is how to amend your changes and retag:
|
||
```sh
|
||
# Amend changes
|
||
git commit --amend --no-edit
|
||
|
||
# Retag while reusing the previous tag's annotation
|
||
git tag -l --format='%(contents)' vX.Y.Z > tag_msg.tmp
|
||
git tag -F tag_msg.tmp -as -f vX.Y.Z
|
||
rm tag_msg.tmp
|
||
```
|
||
|
||
Note: **DO NOT** retag if you already pushed you changes. If you made a
|
||
mistake (it happens to everybody), just create a new release.
|
||
|
||
|
||
## Step 3
|
||
|
||
Check that the release commit is properly tagged:
|
||
```sh
|
||
# Either with git log (colorful, also shows the branches/tags on the remote)
|
||
git log --pretty=oneline -3
|
||
|
||
# Or using git tag (only shows the tag(s) pointing to HEAD)
|
||
git tag --points-at HEAD
|
||
```
|
||
|
||
If not, go back to step 2.
|
||
|
||
|
||
## Step 4
|
||
|
||
Edit `shard.yml` again to add `-dev` to the version string. If you didn't already, also add a "future version" title line to the
|
||
top of the changelog under which future PR will be listed.
|
||
|
||
[Example commit](https://github.com/iv-org/invidious/commit/98926047586154269bb269d01e3e52e60e044035)
|
||
|
||
Commit your changes:
|
||
```
|
||
git add CHANGELOG.md shard.yml
|
||
git commit -S -m "Prepare for next release"
|
||
```
|
||
|
||
# Step 5
|
||
|
||
Once you have checked everything, push to GitHub:
|
||
```sh
|
||
git push origin master
|
||
git push origin vX.Y.Z
|
||
```
|
||
|
||
|
||
## Step 6
|
||
|
||
Got to GitHub to make a new release:
|
||
https://github.com/iv-org/invidious/releases/new
|
||
|
||
Select the tag your previously created, leave `target` set to `master`,
|
||
and then copy paste the text you wrote to `CHANGELOG.md` (both the summary and
|
||
the list of PRs merged since last release).
|
||
|
||
And then click "publish"!
|