Skip to content

doc: simplify and streamline release procedure #2177

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nodiscc merged 4 commits into from
Jan 23, 2026
Merged

doc: simplify and streamline release procedure #2177

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3bd9bd5
build: add make bump_version target to automate version updates
nodiscc Jan 23, 2026
bd81415
docs: combine AUTHORS update and version bump into single commit
nodiscc Jan 23, 2026
92a9427
docs: simplify, remove tag verification example from release procedure
nodiscc Jan 23, 2026
b77f409
docs: make CHANGELOG.md the source of truth for release notes
nodiscc Jan 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,20 @@ release_zip: composer_dependencies htmldoc translate build_frontend
zip -r $(ARCHIVE_VERSION).zip $(ARCHIVE_PREFIX)tpl/
rm -rf $(ARCHIVE_PREFIX)

### bump version number in all relevant files
bump_version:
ifndef VERSION
$(error VERSION is not set. Usage: make bump_version VERSION=x.y.z)
endif
@echo "Bumping version to $(VERSION)..."
@sed -i 's|/\* .* \*/|/* $(VERSION) */|' shaarli_version.php
@sed -i "s/^version = '.*'/version = '$(VERSION)'/" doc/conf.py
@sed -i "s/^release = '.*'/release = '$(VERSION)'/" doc/conf.py
@sed -i "s|/badge/release-v[^-]*-|/badge/release-v$(VERSION)-|" README.md
@sed -i "s|/releases/tag/v[0-9.]*|/releases/tag/v$(VERSION)|" README.md
@echo "Version bumped to $(VERSION)"
@echo "Please review the changes with 'git diff' before committing."

##
# Targets for repository and documentation maintenance
##
Expand Down
46 changes: 12 additions & 34 deletions doc/md/dev/Development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -395,14 +395,14 @@ This guide assumes that you have:

### Release notes and `CHANGELOG.md`

GitHub allows drafting the release notes for the upcoming release, from the [Releases](https://github.com/shaarli/Shaarli/releases) page. This way, the release note can be drafted while contributions are merged to `master`. See https://keepachangelog.com/en/0.3.0/ for changelog formatting.

`CHANGELOG.md` should contain the same information as the release note draft for the upcoming version. Update it to:
Update `CHANGELOG.md` to:

- add new entries (additions, fixes, etc.)
- mark the current version as released by setting its date and link
- add a new section for the future unreleased version

See https://keepachangelog.com/en/0.3.0/ for changelog formatting.

```bash
## [v0.x.y](https://github.com/shaarli/Shaarli/releases/tag/v0.x.y) - UNRELEASED

Expand All @@ -420,20 +420,12 @@ GitHub allows drafting the release notes for the upcoming release, from the [Rel

```

### Update the list of Git contributors

```bash
$ make generate_authors
$ git add AUTHORS
$ git commit -m "doc: update AUTHORS"
```

### Create and merge a Pull Request

Create a Pull Request to merge changes from your remote, into `master` in the community Shaarli repository, and have it merged.


### Create the release branch and update shaarli_version.php
### Create the release branch and update version

```bash
# fetch latest changes from master to your local copy
Expand All @@ -451,10 +443,11 @@ $ git merge master
# Check that everything went fine:
$ make test

# Bump shaarli_version.php from dev to 0.x.0, **without the v**
$ vim shaarli_version.php doc/conf.py README.md
$ git add shaarli_version doc/conf.py README.md
$ git commit -m "bump Shaarli version to v0.x.0"
# Update AUTHORS and bump version to 0.x.0 (without the v prefix)
$ make generate_authors
$ make bump_version VERSION=0.x.0
$ git add AUTHORS shaarli_version.php doc/conf.py README.md
$ git commit -m "Release v0.x.0"
$ git push upstream v0.x
```

Expand All @@ -474,26 +467,11 @@ git tag -s -m "Release v0.5.0" v0.5.0
git push --tags upstream
```

Here is how to verify a signed tag. [`v0.5.0`](https://github.com/shaarli/Shaarli/releases/tag/v0.5.0) is the first GPG-signed tag pushed on the Community Shaarli. Let's have a look at its signature!

```bash
# update the list of available tags
git fetch upstream

# get the SHA1 reference of the tag
git show-ref tags/v0.5.0
# gives: f7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0

# verify the tag signature information
git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1
# gpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F
# gpg: Good signature from "VirtualTam <virtualtam@flibidi.net>" [ultimate]
```

### Publish the GitHub release

- In the `master` banch, update version badges in `README.md` to point to the newly released Shaarli version
- Update the previously drafted [release](https://github.com/shaarli/Shaarli/releases) (notes, tag) and publish it
- In the `master` branch, update version badges in `README.md` to point to the newly released Shaarli version
- Create a new [release](https://github.com/shaarli/Shaarli/releases) and copy the release notes from `CHANGELOG.md`
- Set the appropriate tag and publish the release
- Profit!


Expand Down