# Release Shaarli

See Git - Maintaining a project - Tagging your [](.html)
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 and Pandoc need to be installed

## 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

    [...][](.html)
    ## vA.B.C - UNRELEASED
    TBA

    ## [vX.Y.Z](https://github.com/shaarli/Shaarli/releases/tag/vX.Y.Z) - YYYY-MM-DD[](.html)
    [...][](.html)

## Increment the version code, create and push a signed tag

### Bump Shaarli's version

    $ cd /path/to/shaarli

    # create a new branch
    $ git fetch upstream
    $ git checkout upstream/master -b v0.5.0

    # bump the version number
    $ vim index.php shaarli_version.php

    # rebuild the documentation from the wiki
    $ make htmldoc

    # commit the changes
    $ git add index.php shaarli_version.php doc
    $ git commit -s -m "Bump version to 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 ;-)

### Create and push a signed tag

    # update your local copy
    $ git checkout master
    $ git fetch upstream
    $ git pull upstream master

    # 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][](.html)

## Publish the GitHub release

### 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:

    $ 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.