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’s worth making sure you’re owner of all gems.
Remember to follow the Gitflow branching workflow.
Create the stable branch for the release
-
Go to develop with
git checkout develop
-
Create the release branch
git checkout -b release/x.y-stable && git push origin release/x.y-stable
. -
If required, add the release branch to Crowdin so that any pending translations will generate a PR to this branch. This needs to be done with the generic user
decidim
in the GitHub’s Crowdin integration, as this is the user that initially configured the installation and other admins in the Crowdin organization can’t change it.
Mark develop
as the reference to the next release:
-
Go back to develop with
git checkout develop
-
Turn develop into the
dev
branch for the next release:-
Update
.decidim-version
to the newdev
development version:x.y.z.dev
, wherex.y.z
is the new semver number for the next version -
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 theGemfile.lock
files -
Run
bin/rake webpack
, this will update the JavaScript bundle.
-
-
Update
SECURITY.md
and change the supported version to the new version. -
Update the
CHANGELOG.MD
. At the top you should have anUnreleased
header with theAdded
,Changed
,Fixed
andRemoved
empty sections. After that, the header with the current version and link with the same beforementioned sections and aPrevious versions
header at the bottom that links to the previous minor release stable branch.
## [Unreleased](https://github.com/decidim/decidim/tree/HEAD)
### Added
### Changed
### Fixed
### Removed
## [v0.XX.0](https://github.com/decidim/decidim/releases/tag/v0.XX.0)
### Added
...
## Previous versions
Please check [0.XX-stable](https://github.com/decidim/decidim/blob/release/0.XX-stable/CHANGELOG.md) for previous changes.
-
Push the changes
git add . && git commit -m "Bump develop to next release version" && git push origin develop
Producing the CHANGELOG.md
Look for the "Bump develop to next release version" commit sha1.
You can do it either visually with gitk .decidim-version
or by blaming git blame .decidim-version
.
Here you have different options to see what happened from one revision to another:
git log v0.20.0..v0.20.1 --grep " (#[0-9]\+)" --oneline
git log <SHA>..HEAD --grep " (#[0-9]\+)" --oneline
Once you’ve checked the list of changes, it’s time to actually generating the changelog.
bin/changelog_generator
Running it as is, or passing it the --help
flag, will render the help section for the script. In order to actually run the script, follow the instructions:
bin/changelog_generator <GITHUB_TOKEN> <SHA>
This command will create a temporary_changelog.md
in the root of the project, so you can inspect this file and generated changelog.
If you have some elements in the Unsorted
section of the output, you can review the PRs individually, fix the title and the tags and rerun the script. Those PRs with the tags fixed will be automatically sorted. Labelling the PRs as they’re opened or merged is encouraged to save some time when producing the changelog.
You can copy-paste the contents of the temporary changelog file to the relevant sections of the Changelog file.
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:
-
Checkout the release stable branch
git checkout release/x.y-stable
. -
Update
.decidim-version
to the new versionx.y.z.rc1
-
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 theGemfile.lock
files -
Run
bin/rake webpack
, this will update the JavaScript bundle. -
Run
bin/rspec
, this will check things like if all the officially supported languages translations are OK. -
Commit all the changes:
git add . && git commit -m "Bump to rcXX version" && git push origin release/x.y-stable
. -
Run
git pull && bin/rake release_all
, this will create all the tags, push the commits and tags and release the gems to RubyGems.
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 todevelop
. -
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:
-
Checkout the release stable branch
git checkout release/x.y-stable
. -
Update
.decidim-version
by removing the.rcN
suffix, leaving a clean version number likex.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 theGemfile.lock
files -
Run
bin/rake webpack
, this will update the JavaScript bundle. -
Update
CHANGELOG.MD
. At the top you should have anUnreleased
header with theAdded
,Changed
,Fixed
andRemoved
empty sections. After that, the header with the current version and link like## [0.20.0](https://github.com/decidim/decidim/tree/v0.20.0)
and again the headers for theAdded
,Changed
,Fixed
andRemoved
sections. -
Commit all the changes:
git add . && git commit -m "Bump to v0.XX.0 final version" && git push origin release/x.y-stable
. -
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 you should 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:
-
Add the new
release/x.y-stable
branch. -
Remove from Crowdin branches that are not officially supported anymore. That way they don’t synchronize with Github.
-
-
Update the
CHANGELOG.MD
inrelease/x.y-stable
. At the top you should have anUnreleased
header with theAdded
,Changed
,Fixed
andRemoved
empty sections. After that, the header with the current version. Add theUnreleased
section or create the new current version section.
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:
-
Checkout the branch you want to release:
git checkout -b release/x.y-stable
-
Update
.decidim-version
to the new version number. -
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 theGemfile.lock
files -
Run
bin/rake webpack
, this will update the JavaScript bundle. -
Update
CHANGELOG.MD
. At the top you should have anUnreleased
header with theAdded
,Changed
,Fixed
andRemoved
empty sections. After that, the header with the current version and link like## [0.20.0](https://github.com/decidim/decidim/tree/v0.20.0)
and again the headers for theAdded
,Changed
,Fixed
andRemoved
sections. -
Commit all the changes:
git add . && git commit -m "Prepare VERSION release"
-
Run
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 you should 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.