-
- -

See Git - Maintaining a project - Tagging your -releases.

-

Prerequisites

-

This guide assumes that you have: -- a GPG key matching your GitHub authentication credentials - - i.e., 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 fork - - upstream 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.

-

GitHub release draft and CHANGELOG.md

-

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

-

GitHub release draft

-

GitHub allows drafting the release note for the upcoming release, from the Releases page. This way, the release note can be drafted while contributions are merged to master.

-

CHANGELOG.md

-

This file 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

-
$ cd /path/to/shaarli
-
-$ nano CHANGELOG.md
-
-[...]
-## vA.B.C - UNRELEASED
-TBA
-
-## [vX.Y.Z](https://github.com/shaarli/Shaarli/releases/tag/vX.Y.Z) - YYYY-MM-DD
-[...]
-
- -

Increment the version code, updated docs, create and push a signed tag

-

Generate documentation

-
$ cd /path/to/shaarli
-
-# create a new branch
-$ git fetch upstream
-$ git checkout upstream/master -b v0.5.0
-
-# rebuild the HTML documentation from Markdown
-$ make htmlpages
-
-# commit the changes
-$ git add doc
-$ git commit -s -m "Generate documentation for v0.5.0"
-
-# push the commit on your GitHub fork
-$ git push origin v0.5.0
-
- -

Create and merge a Pull Request

-

This one is pretty straightforward ;-)

-

Bump Shaarli version to v0.x branch

-
$ git checkout master
-$ git fetch upstream
-$ git pull upstream master
-
-# IF the branch doesn't exists
-$ git checkout -b v0.5
-# OR if the branch already exists
-$ git checkout v0.5
-$ git rebase upstream/master
-
-# Bump shaarli version from dev to 0.5.0, **without the `v`**
-$ vim shaarli_version.php
-$ git add shaarli_version
-$ git commit -s -m "Bump Shaarli version to v0.5.0"
-$ git push upstream v0.5
-
- -

Create and push a signed tag

-
# update your local copy
-$ git checkout v0.5
-$ git fetch upstream
-$ git pull upstream v0.5
-
-# create a signed tag
-$ git tag -s -m "Release v0.5.0" v0.5.0
-
-# push it to "upstream"
-$ git push --tags upstream
-
- -

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!

-
$ cd /path/to/shaarli
-$ git fetch upstream
-
-# get the SHA1 reference of the tag
-$ git show-ref tags/v0.5.0
-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

-

Update release badges

-

Update README.md so version badges display and point to the newly released Shaarli version(s), in the master branch.

-

Create a GitHub release from a Git tag

-

From the previously drafted release: -- edit the release notes (if needed) -- specify the appropriate Git tag -- publish the release -- profit!

-

Generate and upload all-in-one release archives

-

Users with a shared hosting may have: -- no SSH access -- no possibility to install PHP packages or server extensions -- no possibility to run scripts

-

To ease Shaarli installations, it is possible to generate and upload additional release archives, -that will contain Shaarli code plus all required third-party libraries.

-

From the v0.5 branch:

-
$ make release_archive
-
- -

This will create the following archives: -- shaarli-vX.Y.Z-full.tar -- shaarli-vX.Y.Z-full.zip

-

The archives need to be manually uploaded on the previously created GitHub release.

-

Update stable and latest branches

-
$ git checkout latest
-# latest release
-$ git merge v0.5.0
-# fix eventual conflicts
-$ make test
-$ git push upstream latest
-$ git checkout stable
-# latest previous major
-$ git merge v0.4.5 
-# fix eventual conflicts
-$ make test
-$ git push upstream stable
-
- -
-