Releasing new versions

In order to release new version you need to be owner of all the gems at RubyGems, ask one of the owners to add you before releasing. Try gem owner decidim to find out the owners of the gem. It is worth making sure you are owner of all gems.

Release Candidates

Release Candidates are the same as beta versions. They should be ready to go to production, but publicly released just before in order to be widely tested.

If this is a Release Candidate version release, the steps to follow are:

Merge all the Crowdin pull requests created by the user decidim-bot, specially the one that is going to be marged against the release branch release/x.y-stable that should be returned by the provided example search (pick the correct pull request for the release from the results).
Go to develop with git checkout develop
Install the last version of the decidim-maintainers_toolbox gem, and run the releaser command. Mind that for this to work you need locally the gh CLI from GitHub.

gem install decidim-maintainers_toolbox
decidim-releaser --github-token=(gh auth token) --version-type=rc

This will create the stable branch and also create two Pull Requests:
1. One for changing the development version on the develop branch (with title "Bump develop to next release version (x.y.z)")
2. Another for creating the the new release in the stable branch with title Bump to vx.y.z version. Wait for the tests to finish and check that everything is passing before releasing the version. During this process you will have the instructions on how to follow with the process in the command line. One of the tasks is updating Crowdin, you can read more about this in the "Create the stable branch in Crowdin" section of this page.
Review, accept and merge the Pull Request.
Run git pull && bin/rake release_all, this will create all the tags, push the commits and tags and release the gems to RubyGems. Be ready for the One Time Password fill for each of the gems.

Usually, at this point, the release branch is deployed to Metadecidim during, at least, one week to validate the stability of the version.

During the validation period

During the validation period, bugfixes must be implemented directly to the current release/x.y.z-stable branch and ported to develop.
During the validation period, translations to the officially supported languages must be added to Crowdin and, when completed, merged into release/x.y.z-stable.

Major/Minor versions

Release Candidates will be tested in a production server (usually Metadecidim) during some period of time (a week at least). When they are considered ready, it is time for them to be released:

Merge all the Crowdin pull requests created by the user decidim-bot, specially the one that is going to be marged against the release branch release/x.y-stable that should be returned by the provided example search (pick the correct pull request for the release from the results).
Checkout the release stable branch git checkout release/x.y-stable.
Update .decidim-version by removing the .rcN suffix, leaving a clean version number like x.y.z
Run bin/rake update_versions, this will update all references to the new version.
Run bin/rake patch_generators, this will update the Gemfile for the generators to the new version.
Run bin/rake bundle, this will update all the Gemfile.lock files
Run bin/rake webpack, this will update the JavaScript bundle.
Update the CHANGELOG.md. Add the header with the current version and link like ## [0.20.0](https://github.com/decidim/decidim/tree/v0.20.0) and the headers generated by the changelog generator.
Commit all the changes: git add . && git commit -m "Bump to v0.XX.0 final version" && git push origin release/x.y-stable.
Wait for the tests to finish and check that everything is passing before releasing the version. NOTE: When you bump the version, the generator tests will fail because the gems and NPM packages have not been actually published yet (as in sent to rubygems/npm). You may see errors such as No matching version found for @decidim/browserslist-config@~0.xx.y in the CI logs. This should be fine as long as you have ensured that the generators tests passed in the previous commit.
Run git pull && bin/rake release_all, this will create all the tags, push the commits and tags and release the gems to RubyGems.
Once all the gems are published:
1. Re-run the failed generators tests at the release branch.
2. Create a new release at this repository, just go to the releases page and create a new one.
Update Decidim’s Docker repository as explained in the Docker images section below.
Update Crowdin synchronization configuration with GitHub:
1. Add the new release/x.y-stable branch.
2. Remove from Crowdin branches that are not officially supported anymore. That way they do not synchronize with GitHub.
Update the version in the documentation system that we use, Antora. For the decidim repository this is done automatically when bumping the versions. For the documentation repository:
1. Create and push the branch in that repository: git checkout release/0.XX-stable && git push origin release/x.y-stable
2. Add the new version on the antora-playbook.yml branches key, for the both sources (decidim and documentation repository). Do not forget to also remove the oldest and change the new default in the start_page key. For instance for v0.28 this is how it’d look like:

diff --git a/antora-playbook.yml b/antora-playbook.yml
index 31be47c..75c7d5e 100644
--- a/antora-playbook.yml
+++ b/antora-playbook.yml
@@ -1,21 +1,21 @@
 site:
   title: Decidim Docs
   url: https://docs.decidim.org
-  start_page: v0.27@en:ROOT:index.adoc
+  start_page: v0.28@en:ROOT:index.adoc
 content:
   sources:
     - url:
       start_path: en
       branches:
+        - release/0.28-stable
         - release/0.27-stable
-        - release/0.26-stable
         - develop
       edit_url: "https://github.com/decidim/documentation/edit/{refname}/{path}"
     - url: https://github.com/decidim/decidim
       start_path: docs
       branches:
+        - release/0.28-stable
         - release/0.27-stable
-        - release/0.26-stable
         - develop

After you commit this change in develop branch you will have to wait a couple minutes for the automatic deployment to see it live at https://docs.decidim.org.

Releasing patch versions

Releasing new versions from a release/x.y-stable branch is quite easy. The process is very similar from releasing a new Decidim version:

Merge all the Crowdin pull requests created by the user decidim-bot, specially the one that is going to be marged against the release branch release/x.y-stable that should be returned by the provided example search (pick the correct pull request for the release from the results).
Make sure that there are no more PRs to backport. Learn more about Backports.
Checkout the branch you want to release: git checkout -b release/x.y-stable
Install the last version of the decidim-maintainers_toolbox gem, and run the releaser command. Mind that for this to work you need locally the gh CLI from GitHub.

gem install decidim-maintainers_toolbox
decidim-releaser --github-token=(gh auth token) --version-type=patch

This will create a Pull Request for the new release with title Bump to vx.y.z version. Wait for the tests to finish and check that everything is passing before releasing the version. NOTE: When you bump the version, the generator tests will fail because the gems and NPM packages have not been actually published yet (as in sent to rubygems/npm). You may see errors such as No matching version found for @decidim/browserslist-config@~0.xx.y in the CI logs. This should be fine as long as you have ensured that the generators tests passed in the previous commit.
Review, accept and merge the Pull Request.
Run git pull && bin/rake release_all, this will create all the tags, push the commits and tags and release the gems to RubyGems. Be ready for the One Time Password fill for each of the gems.
Once all the gems are published:
1. Re-run the failed generators tests at the release branch.
2. Create a new release at this repository, just go to the releases page and create a new one.
Update Decidim’s Docker repository as explained in the Docker images section.

Docker images for each release

Each release triggers a GitHub workflow that rebuilds and publishes the decidim/docker images to GitHub Container Registry and Docker Hub.

Create the stable branch in Crowdin

You will need to first create the version branch in Crowdin
1. Sign in as manager in Crowdin.
2. Go to the Content tab in the Decidim project
3. Click on the dropdown of the "New folder" button (top right) and select "New Version Branch"
4. On the modal, add the name of the branch. As it does not allow the slash character in the name ("/") you will need to change it to a dot ("."). So, for instance, "release/0.20-stable" would become "release.0.20-stable". See other releases if in doubt, it should be consistent.
5. After creating the version branch, edit it and change the "Title as it appears to translators" to the name with the slash ("release/0.20-stable")
Then you will be able to setup the GitHub integration in Crowdin
1. Sign in as user "Decidim" in Crowdin. NOTE: this user is the only one that can do this.
2. Go to the Integrations tab in the Decidim project
3. Click on GitHub
4. Click on the "Edit" button
5. In the "Select Branches for Translation", search the branch. Click on it.
6. Change the "Service Branch Name" to be consistent with the other branches. So, for instance, "release/0.20-stable" would become "chore/l10n/release/0.20-stable".
7. Click on "Save"
8. After a couple of hours, if there are any changes in Crowdin that would involve this branch, you will see the correspondent "Decidim bot" Pull Request in GitHub.