This guide assumes that you have:
- a GPG key matching your GitHub authentication credentials/email (the email address identified by the GPG key is the same as the one in your
- a GitHub fork of Shaarli
- a local clone of your Shaarli fork, with the following remotes:
originpointing to your GitHub fork
upstreampointing to the main Shaarli repository
- maintainer permissions on the main Shaarli repository, to:
- push the signed tag
- create a new release
- Composer needs to be installed
- The venv Python 3 module needs to be installed for HTML documentation generation.
Release notes and
GitHub allows drafting the release notes for the upcoming release, from the Releases page. This way, the release note can be drafted while contributions are merged to
master. See http://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:
- 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
## [v0.x.y](https://github.com/shaarli/Shaarli/releases/tag/v0.x.y) - UNRELEASES ### Added ### Changed ### Fixed ### Removed ### Deprecated ### Security
Update the list of Git contributors
$ make authors $ git commit -s -m "Update AUTHORS"
Create and merge a Pull Request
Create a Pull Request to marge changes from your remote, into
master in the community Shaarli repository, and have it merged.
Create the release branch and update shaarli_version.php
# fetch latest changes from master to your local copy git checkout master git pull upstream master # If releasing a new minor version, create a release branch $ git checkout -b v0.x # Otherwise just use the existing one $ git checkout v0.x # Get the latest changes $ 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 $ git add shaarli_version $ git commit -s -m "Bump Shaarli version to v0.x.0" $ git push upstream v0.x
Create and push a signed tag
# update your local copy git checkout v0.5 git pull upstream v0.5 # create a signed tag git tag -s -m "Release v0.5.0" v0.5.0 # push the tag to upstream git push --tags upstream
Here is how to verify a signed tag.
v0.5.0 is the first GPG-signed tag pushed on the Community Shaarli. Let's have a look at its signature!
# 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 <firstname.lastname@example.org>" [ultimate]
Publish the GitHub release
- In the
masterbanch, update version badges in
README.mdto point to the newly released Shaarli version
- Update the previously drafted release (notes, tag) and publish it
Generate full release zip archives
Release archives will contain Shaarli code plus all required third-party libraries. They are useful for users who:
- have no SSH access, no possibility to install PHP packages/server extensions, no possibility to run scripts (shared hosting)
- do not want to install build/dev dependencies on their server
git checkout the appropriate branch, then:
# checkout the appropriate branch git checkout 0.x.y # generate zip archives make release_archive
This will create
shaarli-v0.x.y-full.zip. These archives need to be manually uploaded on the previously created GitHub release.
# checkout the 'latest' branch git checkout latest # merge changes from your newly published release branch git merge v0.x.y # fix eventual conflicts with git mergetool... # run tests make test # push the latest branch git push upstream latest