Releasing-a-new-Remmina-version.md

Go to the documentation of this file.

# Releasing a new Remmina version

This page describe the Remmina release workflow, and the steps needed to tag  a new version.

## What is a release?

A release is the distribution of the final version or the newest version of a software application.

Remmina tries to follow the [Semantic Versioning](https://semver.org/), that means, given a version number MAJOR.MINOR.PATCH, increment the:

- MAJOR version when you make incompatible API changes
- MINOR version when you add functionality in a backwards compatible manner
- PATCH version when you make backwards compatible bug fixes

Unfortunately, due to the relatively small number of contributions, we almost always increment the PATCH version, even if we push new features.

This is because we are unable to honor the backlog we have for the next MINOR and MAJOR milestones.

That said, is not strictly important to get mad about the versioning, but if we can follow the above schema, is better.

## What is a tag?

A tag is a pointer to a specific commit, we can have light tags, that can be added and removed as needed and annotated tags.
Annotated tags is an unchangeable (nothing is unchangeable ;-) ) par of Git history, and are used on GitLab and GitHub to create a Release.
In fact releases are a GitHub, GitLab concept, it doesn't exist in Git, Git knows only about tags and annotated tags.

## So, how it happens, Releasing Remmina?

As soon as we agree to release a new version, we have some preparatory tasks to do, and to be sure to don't miss anything, we work on a new branch and submit a merge request.
This is the most important point, as on [GitLab](https://gitlab.com/Remmina/Remmina/-/blob/master/.gitlab/merge_request_templates/Remmina%20Release.md) we have a merge request template for the releases. Instructions for generating the changelog can be found [here](https://gitlab.com/Remmina/Remmina/-/wikis/Contribution/HOWTO-generate-the-changelog).

1. Review the above-mentioned template, and eventually modify it if you see something wrong or missing (like the list of downstream maintainers)
2. Create a new branch starting from the `master` branch, use a name like `rel/v1.4.28`
3. Based on the template be sure, working on the new branch, to update the files as indicated.
4. Commit with the `-s` git flag to sign your commit, and push to the Remmina repository.
5. Create a Merge Request, and wait for feedbacks and pipeline's status.
6. Be sure to link the MR to the right milestones and to issues you want to close automatically upon the merge.
7. Check the labels, you must have the `release` label and whatever suit this specific version.

At this point we have a Merge Request, be sure everything is fine, or ask for a review.

While you wait, prepare yourself to create the annotated tag, while you can do it from the command line, here we focus on the GitLab web interface.

Open the previous tag, to see it raw, you can edit it (do not save afterwards), this will be useful to cut and paste what is common to all Release we do.

For instance, at https://gitlab.com/Remmina/Remmina/-/releases/v1.4.27/edit you will have to copy:

```
**ATTENTION New dependencies introduced with v1.3.5 onwards!**

* appindicator or ayatana-appindicator is now optional, -DHAVE_LIBAPPINDICATOR=OFF will disable the Remmina system tray icon.
* -DWITH_PYTHONLIBS=ON is required for the Python plugin (python3-dev/devel required to build)
* pyhoca-cli is needed for the X2Go plugin, -DWITH_X2GO=ON
* NX, XDMCP and ST have removed.
* Use -DWITH_FREERDP3=ON if you are using the FreeRDP master branch
* libsodium is needed to build Remmina.
* webkit2gtk3 is needed to build the WWW plugin.
* -DWITH_KF5WALLET=ON is a new config option required for the KWallet plugin (and the required kf5wallet libraries to build it).
* News can be turned off with -DWITH_NEWS=OFF
* gtk-vnc is needed for the VNC plugin for GNOME and KVM, -DWITH_GVNC=ON
```

This will have to be updated in case something has been changed. Pay attention to this point because it's used by the downstream maintainer.

When the MR is merged, and you have all the blocks you need, [create a new tag](https://gitlab.com/Remmina/Remmina/-/tags/new), in that page you have to give a name to the tag, like `v1.4.28`, and a message, like `Release v1.4.28`.
Without that optional message, you will create a lightweight tag, and you won't end-up in a Release.

With the new tag, you can [create a Release](https://gitlab.com/Remmina/Remmina/-/releases/new), in that new page, select the corresponding tag, give a title (follow the previous release as the template), add the change log, and push the Big Red Button :-D

You are done!!

## And Now What?

Many things happen behind the scene, as soon as you tag a new version, many systems should detect the new tag, and start to build a new Remmina version, this is true for most of the distro, the flatpak, the Ubuntu Remmina PPA, and the snap (see after).
Still, there are some additional manual steps to take.

1. Wait that all the pipelines are finished and submit a new pipeline from the master (needed for the snap)
2. When the manual pipeline is finished go to https://snapcraft.io/remmina/releases, and promote the new version from edge to the stable channel.
3. Add the new release in [wikidata](https://www.wikidata.org/wiki/Q82148?uselang=en#P348), this is need by some distributions to gather the latest tag.
4. Drop a message to the Debian downstream maintainer, at the moment is @mfvescovi

To access snapcraft you need developer rights, ask one maintainer to add yourself in the developer list.
One time a year you need to refresh the snapcraft authentication token:

```
snapcraft export-login --snaps=remmina -
```

Better to use dev@remmina.org (ask the password to the maintainers), and set `SNAPCRAFT_LOGIN` in the [CI/CD variables](https://gitlab.com/Remmina/Remmina/-/settings/ci_cd) with the new obtained token.

## Appendix

### Authors' list

To get the authors'list I use this git command:

```
git log --pretty=format:"%an <%ae>" | sort | uniq -c | sort -rn | sed -e 's/^ *[0-9]\+ //g'
```

You just need to tailor it a little bit, for instance I remove duplicated entries for authors that have multiple emails, I move up the most active users, but don't be too strict, it shouldn't take more than a couple of minutes.

### To-Do

We should reduce more all the above manual steps, and ideally a Release should happens by itself upon a special merge request, as usual, patches are welcome ;-)