Release Shaarli#
Requirements#
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
~/.gitconfig
) - a GitHub fork of Shaarli
- a local clone of your Shaarli fork, with the following remotes:
origin
pointing to your GitHub forkupstream
pointing 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 CHANGELOG.md
#
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 generate_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#
Git tags are used to identify specific revisions with a unique version number that follows semantic versioning
# 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 <virtualtam@flibidi.net>" [ultimate]
Publish the GitHub release#
- In the
master
banch, update version badges inREADME.md
to point to the newly released Shaarli version - Update the previously drafted release (notes, tag) and publish it
- Profit!
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.tar
, shaarli-v0.x.y-full.zip
. These archives need to be manually uploaded on the previously created GitHub release.
Update the latest
branch#
# 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