decidim 0.27.9 → 0.28.0.rc4

data/docs/modules/develop/pages/guide_development_app.adoc

@@ -6,7 +6,7 @@ app (that you can create with `decidim app_name`) but with a Gemfile pre-configu
 We recommend that you first have a xref:install:manual.adoc[working Decidim app] so that you have fullfilled all the necessary
 system and services requirements, like having a working Ruby installation, PostgreSQL, Node.JS, etc.
 
-You'll need to configure the PostgreSQL database before anything. For this,
+You will need to configure the PostgreSQL database before anything. For this,
 
 . Configure postgresql with a super-user. For instance, for a user called `decidim_development_app_user` with password `changeme`, it'd be:
 
@@ -16,7 +16,7 @@ sudo -u postgres psql -c "CREATE USER decidim_development_app_user WITH SUPERUSE
 ----
 
 [start=2]
-. Save the database configuration in your environment variables configuration. If you've followed the xref:install:manual.adoc[Decidim installation manual],
+. Save the database configuration in your environment variables configuration. If you have followed the xref:install:manual.adoc[Decidim installation manual],
 then you should have a working https://github.com/rbenv/rbenv-vars[rbenv-vars] in your environment:
 
 [source,console]
@@ -38,7 +38,7 @@ bundle install
 bin/rake development_app
 ----
 
-A development_app/ entry appears in the .gitignore file, so you don't have to worry about committing the development app by mistake.
+A development_app/ entry appears in the .gitignore file, so you do not have to worry about committing the development app by mistake.
 
 [NOTE]
 ====
@@ -51,18 +51,23 @@ On creation, these steps are automatically invoked by the generator:
 * `bin/rails db:migrate`
 * `bin/rails db:seed`
 
-Mind that if everything went well you shouldn't need to run these commands manually.
+Mind that if everything went well you should not need to run these commands manually.
 ====
 
 If the default database.yml does not suit your needs you can always configure it at your will and run these steps manually, although
-we recommend that you make the database configurations with environment variables (ENV VARs) so it's easy for you to regenerate the database. 
+we recommend that you make the database configurations with environment variables (ENV VARs) so it is easy for you to regenerate the database.
 
 The last command will set your database and add some example data (called "seed data") so that you can start trying Decidim.
-We don't recommend using seed data for production environments, but it's useful for local development and staging environments.
+We do not recommend using seed data for production environments, but it is useful for local development and staging environments.
 
 Once the app is created you are ready to start the server:
 
-* `bin/rails server`
+* `bin/dev`
+
+[NOTE]
+====
+This script starts the rails web server and also the webpack dev server, so you do not have to worry about starting them separately.
+====
 
 == Migrations
 
@@ -79,7 +84,7 @@ Anyway we recommend re-creating your development_app every once in a while.
 
 == Updating from develop
 
-We recommend that you periodically update your codebase with the last changes from the main repository. For this, you'll need
+We recommend that you periodically update your codebase with the last changes from the main repository. For this, you will need
 to follow these instructions:
 
 [source,console]
@@ -93,7 +98,7 @@ And restart your rails server (with Ctrl+C to stop it).
 
 == Re-creating the development_app
 
-If you're working with old branches or there were multiple changes in develop, you'll need to re-create your development_app.
+If you are working with old branches or there were multiple changes in develop, you will need to re-create your development_app.
 
 [source,console]
 ----

data/docs/modules/develop/pages/guide_development_with_localhost_ssl.adoc

@@ -21,17 +21,17 @@ After that, you can start the development server under SSL at port 3443 (default
 
 Now you are ready to visit your favorite browser at the address `https://localhost:3443/` (note "https" and port 3443). If you would like to test the non-SSL "http" version, it is also running normally at port 3000, so you can access that as you normally would.
 
-Note: Your browser is going to complain as this is a self-signed certificate, that's ok for development, just add an exception and accept the certificate.
+Note: Your browser is going to complain as this is a self-signed certificate, that is ok for development, just add an exception and accept the certificate.
 
 == Testing tenants using lvh.me
 
-You can also test the multi-tenant capabilities of Decidim by using alternative domains or subdomains that points to your local machine. `lvh.me` is a service that does just that without configuring anything in your machine (an alternative is to add entries in your `/etc/hosts` with a testing domain of your choice). Just point your browser to any subdomain of `lvh.me` and you'll be in your own machine.
+You can also test the multi-tenant capabilities of Decidim by using alternative domains or subdomains that points to your local machine. `lvh.me` is a service that does just that without configuring anything in your machine (an alternative is to add entries in your `/etc/hosts` with a testing domain of your choice). Just point your browser to any subdomain of `lvh.me` and you will be in your own machine.
 
 Just access your `/system` admin and create new organization with some subdomain of `lvh.me`: `organization.lvh.me`, `tenant2.lvh.me`, etc.
 
 You can combine this with the previously generated certificate (your browser is going to complaint but just tell it to proceed vising the site).
 
-Finally remember to add the port as `lvh.me` do not forwards anything, for instance (use `http` or `https` depending on how you've started Rails):
+Finally remember to add the port as `lvh.me` do not forwards anything, for instance (use `http` or `https` depending on how you have started Rails):
 
 `http://someorg.lvh.me:3000/`
 
@@ -45,7 +45,7 @@ etc.
 
 == Optional: Create your own self-signed certificate for localhost
 
-If you don't want to rely on the dummy certificate shipped with the `decidim-dev` gem, you can also create the certificates yourself.
+If you do not want to rely on the dummy certificate shipped with the `decidim-dev` gem, you can also create the certificates yourself.
 
 First you need a SSL certificate for the `localhost` domain (you only need to execute this command once):
 
@@ -57,7 +57,7 @@ openssl req -x509 -out localhost.crt -keyout localhost.key \
    printf "[dn]\nCN=localhost\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:localhost\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")
 ----
 
-This will generate two files: `localhost.crt` and `localhost.key`, you can store them anywhere you want to use them later. In this example we'll suppose we have them in the folder `certs` in our root user home:
+This will generate two files: `localhost.crt` and `localhost.key`, you can store them anywhere you want to use them later. In this example we will suppose we have them in the folder `certs` in our root user home:
 
 [source,bash]
 ----

data/docs/modules/develop/pages/guide_example_apps.adoc

@@ -1,15 +1,15 @@
 = Example Apps
 
-If you have worked in the past with Ruby on Rails, you'll notice quickly that Decidim is *not* your typical Ruby on Rails Vanilla App.
+If you have worked in the past with Ruby on Rails, you will notice quickly that Decidim is *not* your typical Ruby on Rails Vanilla App.
 
-We've tried using http://decide.es[Consul] but we found some problems on reutilization, adaptation, modularization and configuration. You can read more about that on https://alabs.gitbooks.io/propuesta-de-cambios-en-la-arquitectura-de-consul/content/[Propuesta de Cambios de Arquitectura de Consul (in spanish only)]. As a summary, we decided to try with a model based in https://guides.rubyonrails.org/engines.html[RoR Engines]. A good resource regarding this approach is https://cbra.info/[Component Based Rails Applications].
+We have tried using http://decide.es[Consul] but we found some problems on reutilization, adaptation, modularization and configuration. You can read more about that on https://alabs.gitbooks.io/propuesta-de-cambios-en-la-arquitectura-de-consul/content/[Propuesta de Cambios de Arquitectura de Consul (in spanish only)]. As a summary, we decided to try with a model based in https://guides.rubyonrails.org/engines.html[RoR Engines]. A good resource regarding this approach is https://cbra.info/[Component Based Rails Applications].
 
 == What this means
 
 This means that:
 
 . Decidim is a https://rubygems.org/gems/decidim[gem], available in rubygems.org. You can install it with the command `gem install decidim`
-. Decidim is a command line generator of Ruby on Rails applications. After you've install it you can generate a new RoR app with `decidim HelloWorld`
+. Decidim is a command line generator of Ruby on Rails applications. After you have install it you can generate a new RoR app with `decidim HelloWorld`
 . This app has a dependency the gem itself. You can see this in the Gemfile of the generated app.
 . This app can be extended by making changes in the app (see xref:customize:index.adoc[Customising]) and by working with https://decidim.org/modules[Modules].
 
@@ -29,7 +29,7 @@ Some highlights:
 
 * They have their https://github.com/City-of-Helsinki/decidim-helsinki/blob/b9a09e570eb6090dee93f2ee73b5951882c74755/Gemfile[Gemfile] with lots of modules with their own code. Some of them are also in ruybgems (like `decidim-access_requests`, `decidim-antivirus`, `decidim-mpassid`, `decidim-process_groups_content_block`, `decidim-suomifi`, `decidim-term_customizer`), others are only in Github (`decidim-accountability_simple`, `decidim-apiauth`, `decidim-combined_budgeting`, `decidim-plans`, `decidim-redirects`). They even use a module made by other organization in the community (`decidim-budgets_enhanced`)
 * They have their UI customized to their needs. See the https://github.com/City-of-Helsinki/decidim-helsinki/tree/a7396a312cc04198654a86d66c2a7de556c212af/app/assets/stylesheets[CSS] and https://github.com/City-of-Helsinki/decidim-helsinki/tree/a7396a312cc04198654a86d66c2a7de556c212af/app/views[HTML (views)].
-* They have an awesome READE explaining how it works and what changes have made.
+* They have an awesome README explaining how it works and what changes have made.
 
 === Decidim Barcelona
 

data/docs/modules/develop/pages/guide_github_projects.adoc

@@ -1,11 +1,11 @@
 = GitHub Projects Workflow
 
-This is an internal document on how we're organizing the development of Decidim with external contractors through Github projects.
+This is an internal document on how we are organizing the development of Decidim with external contractors through Github projects.
 
 There are three teams:
 
 1. Product team: formed by representatives of the Barcelona City Council, Localret and Decidim Association who make functional decisions. They have the product vision and ensure that all the developments that are merged are coherent and consistent. You can summon them by mentioning in GitHub at @decidim/product
-2. Contractors: depends on the project. Most of the current developments are funded by the city of Barcelona, and the teams depend on the contract that has won the public procurement process. If there's any published contract we link it in the description of the project.
+2. Contractors: depends on the project. Most of the current developments are funded by the city of Barcelona, and the teams depend on the contract that has won the public procurement process. If there is any published contract we link it in the description of the project.
 3. Maintainers: developers that make the releases, review the Pull Requests, update dependencies and generally take care of all the Decidim source code. You can summon them by mentioning in GitHub at @decidim/core
 
 We follow some rules of Agile Development (mostly Scrum and KanBan).

data/docs/modules/develop/pages/guide_migrate_webpacker_app.adoc

@@ -6,7 +6,7 @@ NOTE: this recipe might not work for all the cases, it tries to cover the generi
 
 == About Webpacker
 
-It's recommended to understand how Webpacker works. More information:
+It is recommended to understand how Webpacker works. More information:
 
 * https://github.com/rails/webpacker#usage[Webpacker README]
 * https://edgeguides.rubyonrails.org/webpacker.html[Rails Webpacker guide]
@@ -56,7 +56,7 @@ app/packs:
   └── images
 ----
 
-If it's not the case you must create it. Then, copy Decidim customizable assets
+If it is not the case you must create it. Then, copy Decidim customizable assets
 
 * Copy the file https://github.com/decidim/decidim/blob/develop/decidim-generators/lib/decidim/generators/app_templates/decidim_application.js[decidim_application.js] to `app/packs/src/decidim/decidim_application.js`
 * Copy the file https://github.com/decidim/decidim/blob/develop/decidim-generators/lib/decidim/generators/app_templates/decidim_application.scss[decidim_application.scss] to `app/packs/stylesheets/decidim/decidim_application.scss`
@@ -98,7 +98,7 @@ So, if you have a file in a subdirectory such as `app/packs/images/subfolder/tes
 
 Existing stylesheets should be moved from `app/assets/stylesheets` to `app/packs/stylesheets` and imported with `@import` into `decidim_application.scss`. Take into account that you might need to adjust a bit the paths of the `@import` to adjust them to the new locations.
 
-If that CSS file is replacing a Decidim file, there's no need to add it to `decidim_application.scss`.
+If that CSS file is replacing a Decidim file, there is no need to add it to `decidim_application.scss`.
 
 If any of the CSS is re-defining CSS vars add them to `_decidim-settings.scss`.
 
@@ -106,11 +106,11 @@ If any of the CSS is re-defining CSS vars add them to `_decidim-settings.scss`.
 
 Existing javascripts should be moved from `app/assets/javascsripts` to `app/packs/src` and imported with `import` into `decidim_application.js`. Take into account that you might need to adjust a bit the paths of the `import` to adjust them to the new locations.
 
-If that JS file is replacing a Decidim file, there's no need to add it to `decidim_application.js`
+If that JS file is replacing a Decidim file, there is no need to add it to `decidim_application.js`
 
 === Update Rails helpers
 
-`javascript_include_tag` and `stylesheet_link_tag` have been replaced by `javascript_pack_tag` and `stylesheet_pack_tag`. This only needs to be done if you're modifying the `application.html` file or partial in your layout.
+`javascript_include_tag` and `stylesheet_link_tag` have been replaced by `javascript_pack_tag` and `stylesheet_pack_tag`. This only needs to be done if you are modifying the `application.html` file or partial in your layout.
 
 For images, if they are in `app/packs/images` you need to replace `ìmage_tag` with `image_pack_tag`.
 
@@ -118,7 +118,7 @@ For images, if they are in `app/packs/images` you need to replace `ìmage_tag` w
 
 Sometimes assets are included in `vendor/assets/` folder or imported from gems. For each specific one you should check:
 
-1. if the asset is a javascript that is available as npm package the recommendation is to add it to package.json with `npm install`. If it's not available you might want to copy it to `app/packs/src` and import it.
+1. if the asset is a javascript that is available as npm package the recommendation is to add it to package.json with `npm install`. If it is not available you might want to copy it to `app/packs/src` and import it.
 2. if the asset is a stylesheet it should be copied to `app/packs/stylesheets` and imported with `@import...` from `_decidim-settings.scss`. Alternatively you can use the optional asset includes as described below to include these in the Decidim main SCSS files.
 
 === Migrate uploads to ActiveStorage
@@ -215,7 +215,7 @@ namespace :deploy do
 end
 ----
 
-Also, in the case of Capistrano it's interesting to add to the shared_paths the following folders:
+Also, in the case of Capistrano it is interesting to add to the shared_paths the following folders:
 
 * `storage` *IMPORTANT!*
 * `tmp/webpacker-cache`
@@ -233,7 +233,7 @@ npm ERR! ERESOLVE unable to resolve dependency tree
 npm ERR!
 ----
 
-Then you need to check again that you're using the correct Node.js and NPM versions.
+Then you need to check again that you are using the correct Node.js and NPM versions.
 
 In some case it might be that some packages are not well resolved when installing NPM modules. If you get messages like:
 
@@ -244,7 +244,7 @@ In some case it might be that some packages are not well resolved when installin
 ...
 ----
 
-These might be due some kind of corruption in your `package-json.lock` file, you can try either to remove this file and recreate it with `npm install` or to add the package `@rails/webpacker` manually in your `package.json` file next to the `@decidim/webpacker` package:
+These might be due some kind of corruption in your `package-lock.json` file, you can try either to remove this file and recreate it with `npm install` or to add the package `@rails/webpacker` manually in your `package.json` file next to the `@decidim/webpacker` package:
 
 [source,json]
 ----

data/docs/modules/develop/pages/guide_migrate_webpacker_module.adoc

@@ -4,7 +4,7 @@ Decidim modules are included to Decidim apps as gems. Since the introduction of
 
 == About Webpacker
 
-It's recommended to understand how Webpacker works. More information:
+It is recommended to understand how Webpacker works. More information:
 
 * https://github.com/rails/webpacker#usage
 * https://edgeguides.rubyonrails.org/webpacker.html
@@ -17,7 +17,7 @@ Once created, you should update the instructions to install the module and add t
 
 == Folder migration
 
-It's recommend to migrate to the new folders structure:
+It is recommend to migrate to the new folders structure:
 
 ```
 app/packs:

data/docs/modules/develop/pages/index.adoc

@@ -0,0 +1,32 @@
+= Develop
+
+* xref:develop:guide.adoc[Guide]
+* xref:develop:security.adoc[Security]
+
+== Decidim instances
+
+Decidim developers should first understand how to create their own Decidim instances before contributing back to the core.
+
+Start by xref:configure:index.adoc[creating your own Decidim instance] after which you can learn how to develop it further.
+
+== Customize
+
+The next phase in the learning process is to understand how you can customize the different functionality that Decidim provides in case you are not satisfied with the defaults it provides.
+
+Learn more about customizing Decidim from the xref:customize:index.adoc[Customize guide].
+
+== Modules
+
+Once you know the basics of Decidim, it is a great idea to learn creating your own modules before jumping into the Decidim core development. This way you can generally create the functionality that you need faster than providing it to the Decidim core as a pull request as that process takes longer. By modularizing your features it makes it also easier to provide them to the core at later stages.
+
+Learn more about module development from the xref:develop:modules.adoc[Module development guide].
+
+== Core development
+
+Once you feel you know Decidim well enough or want to fix a bug you found in the core, you can start learning more about core development. Note that the easiest way to get your core contributions accepted is to fix bugs and provide small improvements that do not change anything in the current functionality.
+
+First you need to understand the contribution process and the governance around it. To learn more about this topic, read through the xref:contribute:index.adoc[Contribute guide].
+
+== Security
+
+Security is very important to us. Please read through our xref:develop:security.adoc[Security policy] to learn how to report security issues.

data/docs/modules/develop/pages/machine_translations.adoc

@@ -24,7 +24,7 @@ In order to test the `Decidim::Dev::DummyTranslator` you will need to add at the
 Some translation services are async, which means that some extra work is needed. This is the main overview:
 
 * The Translation service will only send the translation request. It should have a way to send what resource, field and target locale are related to that translation.
-* You'll need to create a custom controller in your application to receive the callback from the translation service when the translation is finished
+* You will need to create a custom controller in your application to receive the callback from the translation service when the translation is finished
 * From that new endpoint, find a way to find the related resource, field and target locale. Then start a `Decidim::MachineTranslationSaveJob` with that data. This job will handle how to save the data in the DB.
 
 == Enabling the integration, installation-wise

data/docs/modules/develop/pages/maintainers/releases.adoc

@@ -0,0 +1,297 @@
+= 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.
+
+Remember to follow the Gitflow branching workflow.
+
+== Create the stable branch for the release
+
+. Merge all the https://github.com/decidim/decidim/pulls?q=is%3Apr+is%3Aopen+author%3Adecidim-bot+sort%3Aupdated-desc+base%3Adevelop[Crowdin pull requests created by the user `decidim-bot`], specially the one that is going to be marged against `develop` that should be returned by the provided example search.
+. 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`.
+. 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 cannot change it. See instructions for this on the "Create the stable branch in Crowdin". Note that after the branch is configured at Crowdin, it takes some time for the synchronization to happen, so be prepared to wait a couple of hours.
+
+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 new `dev` development version: `x.y.z.dev`, where `x.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 bundle`, this will update all the `Gemfile.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 an `Unreleased` header and under that the content `Nothing.`. The CHANGELOG is automatically generated for the release branches so do not worry about its actual contents at the `develop` branch.
+After that, the header with the current version and link with the same beforementioned sections and a `Previous versions` header at the bottom that links to the previous minor release stable branch.
+
+[source,markdown]
+----
+# Changelog
+
+## [Unreleased](https://github.com/decidim/decidim/tree/HEAD)
+
+Nothing.
+
+...
+
+## Previous versions
+
+Please check [0.XX-stable](https://github.com/decidim/decidim/blob/release/0.XX-stable/CHANGELOG.md) for previous changes.
+----
+
+. Update the `RELEASE_NOTES.md`
+You can use the following template for the new `RELEASE_NOTES.md`:
+
+[source,markdown]
+----
+# Release Notes
+
+## 1. Upgrade notes
+
+As usual, we recommend that you have a full backup, of the database, application code and static files.
+
+To update, follow these steps:
+
+### 1.1. Update your Gemfile
+
+```ruby
+gem "decidim", github: "decidim/decidim"
+gem "decidim-dev", github: "decidim/decidim"
+```
+
+### 1.2. Run these commands
+
+```console
+bundle update decidim
+bin/rails decidim:upgrade
+bin/rails db:migrate
+```
+
+### 1.3. Follow the steps and commands detailed in these notes
+
+## 2. General notes
+
+## 3. One time actions
+
+These are one time actions that need to be done after the code is updated in the production database.
+
+### 3.1. [[TITLE OF THE ACTION]]
+
+You can read more about this change on PR [\#XXXX](https://github.com/decidim/decidim/pull/XXXX).
+
+## 4. Scheduled tasks
+
+Implementers need to configure these changes it in your scheduler task system in the production server. We give the examples
+ with `crontab`, although alternatively you could use `whenever` gem or the scheduled jobs of your hosting provider.
+
+### 4.1. [[TITLE OF THE TASK]]
+
+```bash
+4 0 * * * cd /home/user/decidim_application && RAILS_ENV=production bundle exec rails decidim:TASK
+```
+
+You can read more about this change on PR [\#XXXX](https://github.com/decidim/decidim/pull/XXXX).
+
+## 5. Changes in APIs
+
+### 5.1. [[TITLE OF THE CHANGE]]
+
+In order to [[REASONING (e.g. improve the maintenance of the code base)]] we have changed...
+
+If you have used code as such:
+
+```ruby
+# Explain the usage of the API as it was in the previous version
+result = 1 + 1 if before
+```
+
+You need to change it to:
+
+```ruby
+# Explain the usage of the API as it is in the new version
+result = 1 + 1 if after
+```
+----
+
+. Push the changes `git add . && git commit -m "Bump develop to next release version" && git push origin develop`
+
+== Create the stable branch in Crowdin
+
+. You will need to first create the version branch in Crowdin
+ .. Sign in as manager in Crowdin.
+ .. Go to the https://translate.decidim.org/project/decidim/content/files[Content tab in the Decidim project]
+ .. Click on the dropdown of the "New folder" button (top right) and select "New Version Branch"
+ .. 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.
+ .. 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
+ .. Sign in as user "Decidim" in Crowdin. NOTE: this user is the only one that can do this.
+ .. Go to the https://translate.decidim.org/project/decidim/apps[Integrations tab in the Decidim project]
+ .. Click on GitHub
+ .. Click on the "Edit" button
+ .. In the "Select Branches for Translation", search the branch. Click on it.
+ .. 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".
+ .. Click on "Save"
+ .. 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.
+
+== 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:
+
+[source,bash]
+----
+git log v0.20.0..v0.20.1 --grep " (#[0-9]\+)" --oneline
+git log <SHA>..HEAD --grep " (#[0-9]\+)" --oneline
+----
+
+Once you have checked the list of changes, it is time to actually generating the changelog.
+
+[source,bash]
+----
+bin/changelog_generator
+----
+
+In order to generate the changelog, you need to know the SHA hash of the first commit that was not part of the previous release. You can check the commit hash by inspecting the commit log of the `.decidim-version` file as follows when in the correct release branch:
+
+[source,bash]
+----
+git log -1 --format=oneline .decidim-version
+----
+
+Alternatively, you can find the first commit after the point of time that the two release branches have separated from each other as follows:
+
+[source,bash]
+----
+git log --reverse --pretty=format:"%H" $(git merge-base release/0.XX-stable release/0.YY-stable)..release/0.YY-stable | head -1
+----
+
+In the above command, replace `0.XX` with the previous release and `0.YY` with the current release you are generating the change log for. This command works only for major releases, not for patch or bugfix releases.
+
+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:
+
+[source,bash]
+----
+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 are 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:
+
+. Merge all the https://github.com/decidim/decidim/pulls?q=is%3Apr+is%3Aopen+author%3Adecidim-bot+sort%3Aupdated-desc[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` to the new version `x.y.z.rc1`
+. Run `bin/rake update_versions`, this will update all references 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.
+. 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`.
+. 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.
+
+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 https://github.com/decidim/decidim/pulls?q=is%3Apr+is%3Aopen+author%3Adecidim-bot+sort%3Aupdated-desc[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 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:
+ .. Re-run the failed generators tests at the release branch.
+ .. Create a new release at this repository, just go to the https://github.com/decidim/decidim/releases[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 do not synchronize with Github.
+. Update the version in the documentation system that we use, Antora. For the https://github.com/decidim/decididm[decidim repository] this is done automatically when bumping the versions. For the https://github.com/decidim/documentation[documentation repository]:
+... Create and push the branch in that repository: `git checkout release/0.XX-stable && git push origin release/x.y-stable`
+... Add the new version on the https://github.com/decidim/documentation/blob/develop/antora-playbook.yml[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:
+[source,diff]
+----
+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
+     - url: https://github.com/decidim/decidim-bulletin-board
+       start_path: docs
+----
+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 https://github.com/decidim/decidim/pulls?q=is%3Apr+is%3Aopen+author%3Adecidim-bot+sort%3Aupdated-desc[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 xref:develop:backports.adoc[Backports].
+. 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 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 "Prepare VERSION release"`
+. 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:
+ .. Re-run the failed generators tests at the release branch.
+ .. Create a new release at this repository, just go to the https://github.com/decidim/decidim/releases[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 https://github.com/decidim/decidim/blob/develop/.github/workflows/on_release.yml[GitHub workflow] that rebuilds and publishes the https://github.com/decidim/docker[decidim/docker images] to https://github.com/orgs/decidim/packages[GitHub Container Registry] and https://hub.docker.com/repository/docker/decidim/decidim[Docker Hub].