decidim 0.27.9 → 0.28.0.rc4

data/docs/modules/install/pages/empty-database.adoc

@@ -1,9 +1,8 @@
 = Empty database installation
 
-You may want to setup your decidim with an empty database.
-In this case, please follow the steps bellow:
+You may want to setup your Decidim installation with an empty database to take full control of all aspects of the Decidim organization. Please follow the steps bellow to start with an empty database:
 
-. Follow steps 1 through 5 of previous section(xref:install:manual.adoc[Manual Installation] section).
+. Follow steps 1 through 5 of the xref:install:manual.adoc[Manual installation tutorial].
 
 . Run the migrations from the root of your project in the terminal.
 [source,bash]
@@ -11,22 +10,25 @@ In this case, please follow the steps bellow:
 bin/rails db:create db:migrate
 ----
 [start=3]
-. Now you need to create your admin user, in order to be able to login to the system. in the terminal type the following:
+. Create a system admin account to log in to the system panel with the following command and follow the instructions shown in the terminal:
 [source,bash]
+  * For the sake of conformity with the rest of documentation, you can create a user with email `system@example.org` and password `decidim123456789`. Of course this is not recommended for a production environment as it is not secure.
 ----
-bundle exec rails s
+bin/rails decidim_system:create_admin
 ----
 [start=4]
-. Then you can create a system admin account to log in to the system panel with the following command:
+. To create your organization's admin user, start the server and configure the organization from the system panel:
 [source,bash]
 ----
-bin/rails decidim_system:create_admin
+bundle exec rails s
 ----
 
-Follow the CLI to create your admin user. For the sake of conformity with the rest of documentation, you may create a user with email `system@example.org` and password `decidim123456789`. Of course this is not recommended for a production environment as it isn't secure.
+Now, you will be able to login to the system panel with the provided credentials. The application automatically redirects you to the system panel when you do not have any organizations configured and when you enter the system's URL in your browser. The default URL for development is `http://localhost:3000`.
+
+After you have configured the organization from the system panel, log out of the system panel and type in the URL of the organization to the browser after which you should see a rather empty home page of your organization. You can now login with the admin user you created when configuring the organization. Note that you will need to set a password for the admin user before being able to login with that user.
 
-Now, you will be able to login to the system panel with the provided credentials.
+At the development environment, you have https://github.com/ryanb/letter_opener[Letter opener] available for viewing the emails that the system sends. You can access it through the `/letter_opener` URL within the domain where your Rails server is running at (typically `http://localhost:3000`).
 
 == Extra notes
 
-The objective of decidim is to define an organizational and representation system capable of transforming into an autonomous entity or association from which the whole community participate. Therefore, creating the organizational account is centric part of the process (refer to xref:admin:system.adoc[System panel] for more information).
+Decidim is a https://en.wikipedia.org/wiki/Multitenancy[multitenant] application that allows you to host multiple different Decidim-based websites within the same system. Organizations are isolated from each other and users in those organizations cannot see any data from other organizations. Therefore, creating the organization is a key part of the process when setting up Decidim. To learn more about the system panel and organizations, refer to the xref:admin:system.adoc[System] panel documentation.

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

@@ -1,21 +1,26 @@
 = Getting started with Decidim
 :source-highlighter: highlightjs
 
-== What is and what isn't Decidim?
+== What is Decidim?
 
-Decidim is a set of Ruby on Rails engines to create a participatory democracy framework on top of a Ruby on Rails app. This system allows having Decidim code separated from custom code for each installation and still enabling easy updates.
+Decidim is a participatory democracy framework based on multiple Ruby on Rails engines that are mounted on top of a Ruby on Rails application. This system allows separating the Decidim core code from any custom code needed in Decidim installations. This approach also makes it easy to keep the core code updated while maintaining any custom functionality added to the platform separated from the core code.
 
-These libraries are published to Rubygems.org, so you can add Decidim to your Ruby on Rails app as external dependencies.
+These libraries (gems) are published to Rubygems.org, and they are added to the Decidim applications by defining them as external dependencies within the Ruby on Rails application.
 
-If you want to start your own installation of Decidim, you don't need to clone this repo. Keep reading to find out how to install Decidim.
+[NOTE]
+====
+We may refer to engines, libraries, gems, or modules; they are mostly the same. Technically there are some differences with these terms but when you first start learning about Decidim and Ruby on Rails, you can see them as synonyms.
+====
+
+If you want to start your own installation of Decidim, you do not need to clone the Decidim source code repository. Keep reading to find out how to install Decidim.
 
 == Creating your Decidim app
 
 === A. Recommended: manual installation
 
-If you know Ruby and have already worked with Ruby on Rails, you need to know that decidim is a gem and a command line that generates an application that consumes this gem 😅.
+If you know Ruby and have already worked with Ruby on Rails, you need to know that `decidim` is a gem and a command line utility that generates a Decidim application. The generated application utilizes the other gems provided by the Decidim project to benefit from the functionality provided by each gem.
 
-The flow is: install gem, generate a Ruby on Rails app, enjoy.
+The flow is: install the `decidim` gem, generate a Ruby on Rails app, enjoy.
 
 [source,console]
 ----
@@ -27,7 +32,7 @@ You can see the xref:install:manual.adoc[official manual installation tutorial],
 
 === B. Installation script [experimental]
 
-There's also an installation script made by http://www.platoniq.net/[Platoniq] that allows you to install Decidim automatically. You can even check it on a Vagrant virtual machine if you want to. https://platoniq.github.io/decidim-install/script/[More information].
+There is also an installation script made by http://www.platoniq.net/[Platoniq] that allows you to install Decidim automatically. You can even check it on a Vagrant virtual machine if you want to. https://platoniq.github.io/decidim-install/script/[More information].
 
 [source,console]
 ----
@@ -36,7 +41,12 @@ chmod +x install-decidim.sh
 ./install-decidim.sh decidim_application
 ----
 
-== Initializing your app for local development
+== Initializing your application for local development
+
+[NOTE]
+====
+The commands below will add lots of example seed data to the Decidim application. This may be confusing for new users if you only want to use Decidim for a specific purpose, such as collecting proposals or arranging participatory budgeting. If you want to start with an empty database (without any seeds) and configure the system yourself, please refer to xref:install:empty-database.adoc[Empty database installation] manual.
+====
 
 You should now setup your database:
 
@@ -45,7 +55,7 @@ You should now setup your database:
 bin/rails db:create db:migrate db:seed
 ----
 
-This will also create some default data so you can start testing the app:
+This will also create some example data through the seeds so that you can start testing the application straight away. The following table contains some example user accounts that you can start testing the system with.
 
 .Default seed's users
 |===
@@ -71,9 +81,7 @@ This will also create some default data so you can start testing the app:
 
 |===
 
-This data won't be created in production environments, if you still want to do it, run: `$ SEED=true rails db:setup`. We recomend that you first login as system user and edit the host for the organization. Set it to you production host, without the protocol and the port (so if your host is `+https://example.org:3001+`, you need to write `example.org`). After it'd be good to execute the `seed` command, as that would be created with the first Organization created.
-
-If you want to verify yourself against the default authorization handler use a document number ended with "X".
+This data will not be created in production environments. If you insist on adding it in production, run: `$ SEED=true rails db:setup`. We recomend that you first login as a system user and edit the hostname for the organization. Set it as your production environment's domain, without the protocol and the port (so if your domain/hostname is `+https://example.org:3000+`, you need to write `example.org` in the organization's host field).
 
 You can now start your server!
 
@@ -86,13 +94,13 @@ Visit http://localhost:3000 to see your app running.
 
 == Configuration & setup
 
-Decidim comes pre-configured with some safe defaults, but can be changed through xref:configure:environment_variables.adoc[Environment Variables] or the xref:configure:initializer.adoc[Initializer] file in your app.
+Decidim comes pre-configured with some sane and safe defaults, but those configurations can be changed through xref:configure:environment_variables.adoc[Environment Variables] or the xref:configure:initializer.adoc[Initializer] file in your app.
 
 === Scheduled tasks
 
-For Decidim to function as expected, there are some background tasks that should be scheduled to be executed regularly. Alternatively you could use `whenever` gem or the scheduled jobs of your hosting provider.
+For Decidim to function as expected, there are some background tasks that should be scheduled to be executed regularly. Alternatively you could use `whenever` gem or the scheduled jobs of your hosting provider. When you are locally testing Decidim for development purposes, you can omit this step or run these tasks manually one by one if you want to test them out.
 
-You can configure it with `crontab -e`, for instance if you've created your Decidim application on /home/user/decidim_application:
+For production environments, you can configure these tasks with `crontab -e`. For instance, if you have created your Decidim application at `/home/user/decidim_application`, you can use the following crontab configuration:
 
 [source,console]
 ----
@@ -116,6 +124,9 @@ You can configure it with `crontab -e`, for instance if you've created your Deci
 
 # Send notification mail digest weekly on saturdays
 5 0 * * 6 cd /home/user/decidim_application && RAILS_ENV=production bundle exec rake decidim:mailers:notifications_digest_weekly
+
+# Change active step in participatory processes
+*/15 * * * * cd /home/user/decidim_application && RAILS_ENV=production bundle exec rake decidim_participatory_processes:change_active_step
 ----
 
 === Further configuration
@@ -123,26 +134,37 @@ You can configure it with `crontab -e`, for instance if you've created your Deci
 We also have other guides on how to configure some extra mandatory components:
 
 * xref:services:activejob.adoc[ActiveJob]: For background jobs (like sending emails).
+* xref:services:activestorage.adoc[ActiveStorage]: For uploading and storing files (like attachments, images, etc.).
 * xref:services:maps.adoc[Maps]: How to enable geocoding for proposals and meetings.
 * xref:services:smtp.adoc[SMTP]: For sending emails for account registrations, password reminders, notifications, etc.
 * xref:services:social_providers.adoc[Social providers integration]: Enable sign up from social networks.
+* xref:customize:authorizations.adoc[Authorizations]: Configure authorizations to verify people's identities
 
 == Deploy
 
-Once you've successfully deployed your app to your favorite platform, you'll need to create your `System` user. First you'll need to create your `Decidim::System` user in your terminal:
+Once you have successfully deployed your applicaton to your favorite platform, you will need to create your `System` user. You can do this using the following command in your terminal:
 
 [source,console]
 ----
 bin/rails decidim_system:create_admin
 ----
 
-You'll be asked for an email and a password. For security, the password will not get displayed back at you and you'll need to confirm it.
+The command asks for an email and a password. For security, the password will not be displayed in the terminal and you need to confirm it by typing it twice.
+
+This will create a system user with the email and password you provided. We recommend using a random password generator and saving it to a password manager, so you have a more secure credentials.
+
+After this, visit the `/system` panel and login with the email and passwords you just entered and create your organization. Now you are ready to setup your organization and after that you are done! 🎉
+
+=== What are organizations?
+
+Decidim is a https://en.wikipedia.org/wiki/Multitenancy[multitenant] application that allows you to host multiple different Decidim-based websites within the same system. Organizations are isolated from each other and users in those organizations cannot see any data from other organizations. This allows you to simplify your hosting configuration if you want to use the same codebase for running multiple websites, with each website having their own content and data. To get started with Decidim, you only need to configure one organization.
 
-This will create a system user with the email and password you set. We recommend using a random password generator and saving it to a password manager, so you have a more secure login.
+Note that the system panel admin user you created earlier is also separated from the user accounts on the organization. When you create the organization, you also provided its admin user's name and email. Decidim will send an email to that address asking that user to create a password for their admin account within the organization. To clarify the difference:
 
-Then, visit the `/system` dashboard and login with the email and passwords you just entered and create your organization. You're done! 🎉
+* *System admin* - Manages the organizations on the same platform, does not necessarily have to be involved in any organization
+* *Organization admin* - Administers a single organization, i.e. manages its content, sets up processes, adds components, manages user accounts, etc.
 
-You can check the https://github.com/decidim/decidim/tree/develop/decidim-system/README.md[`decidim-system` README file] for more info on how organizations work.
+You can read the xref:admin:system.adoc[System panel] documentation for more info on what are organizations and how they work.
 
 == Checklist
 

data/docs/modules/install/pages/manual.adoc

@@ -1,28 +1,24 @@
 = Manual installation tutorial
 
-In order to develop on decidim, you'll need:
+In order to develop on decidim, you will need:
 
 * *Git* 2.34+
 * *PostgreSQL* 14.5+
 * *Ruby* 3.0.2
-* *NodeJS* 16.18.x
-* *Npm* 8.19.x
+* *NodeJS* 18.17.x
+* *Npm* 9.6.x
 * *ImageMagick*
 * *Chrome* browser and https://sites.google.com/a/chromium.org/chromedriver/[chromedriver].
 
-We're starting with an Ubuntu 22.04.1 LTS. This is an opinionated guide, so you're free to use the technology that you are most comfortable. If you have any doubts and you're blocked you can go and ask on https://matrix.to/#/#decidimdevs:matrix.org[our Matrix.org chat room for developers].
-
-The compatibility between the different versions of the components is the following:
-
-include::install:partial$version_matrix.adoc[]
+We are starting with an Ubuntu 22.04.1 LTS. This is an opinionated guide, so you are free to use the technology that you are most comfortable. If you have any doubts and you are blocked you can go and ask on https://matrix.to/#/#decidimdevs:matrix.org[our Matrix.org chat room for developers].
 
 We recommend to have at least some basic proficiency in GNU/Linux (i.e. how to use the command-line, packages, etc), networking knowledge, server administration, development in general, and some basic knowledge about software package managers. It would be great to have Ruby on Rails development basics (a good starting point is http://guides.rubyonrails.org/getting_started.html[Getting Started with Ruby on Rails]) and have some knowledge on how package libraries are working (we use `bundler` for handling ruby packages, and `npm`/`yarn` for handling javascript).
 
-In this guide, we'll see how to install rbenv, PostgreSQL, Node.js and, Decidim, and how to configure everything together for a development environment. Mind that if you want to make a production deployment with real users this guide isn't enough, you should configure a web server (like nginx), backups, monitoring, etc. This is out of the scope of this guide, but you can follow the https://platoniq.github.io/decidim-install/[Platoniq guide].
+In this guide, we will see how to install rbenv, PostgreSQL, Node.js and, Decidim, and how to configure everything together for a development environment. Mind that if you want to make a production deployment with real users this guide is not enough, you should configure a web server (like nginx), backups, monitoring, etc. This is out of the scope of this guide, but you can follow the https://platoniq.github.io/decidim-install/[Platoniq guide].
 
 == 1. Installing rbenv
 
-First, we're going to install https://github.com/rbenv/rbenv[rbenv], for managing various ruby versions. You could also use https://rvm.io/[rvm] or https://github.com/asdf-vm/asdf[asdf] as alternatives on this step.
+First, we are going to install https://github.com/rbenv/rbenv[rbenv], for managing various ruby versions. You could also use https://rvm.io/[rvm] or https://github.com/asdf-vm/asdf[asdf] as alternatives on this step.
 
 [source,bash]
 ----
@@ -39,7 +35,7 @@ rbenv global 3.0.2
 
 == 2. Installing PostgreSQL
 
-Now we're going to install PostgreSQL for the database:
+Now we are going to install PostgreSQL for the database:
 
 [source,bash]
 ----
@@ -91,11 +87,11 @@ git commit -m "Initial commit. Generated with Decidim https://decidim.org"
 == 5. Configure the database
 
 Modify your secrets (see `config/database.yml`). For this you can use https://github.com/laserlemon/figaro[figaro], https://github.com/bkeepers/dotenv[dotenv] or https://github.com/rbenv/rbenv-vars[rbenv-vars]. You
-should always be careful of not uploading your plain secrets on git or your version control system. You can also upload the encrypted secrets, using the sekrets gem or if you're on Ruby on Rails greater than 5.1 you can do it natively.
+should always be careful of not uploading your plain secrets on git or your version control system. You can also upload the encrypted secrets, using the sekrets gem or if you are on Ruby on Rails greater than 5.1 you can do it natively.
 
 For a development environment, and if you are using rbenv, we strongly recommend you to use the https://github.com/rbenv/rbenv-vars[rbenv-vars] to facilitate the edition of ENV vars.
 
-First you'll need to install the rbenv-vars plugin:
+First you will need to install the rbenv-vars plugin:
 
 [source,bash]
 ----
@@ -117,6 +113,11 @@ Be careful where you put the `.rbenv-vars` file, as if you put it in the same fo
 
 == 6. Initializing your app for local development
 
+[NOTE]
+====
+Please refer to xref:install:empty-database.adoc[Empty database installation] section if you want to setup your instance with an empty database (without any seeds).
+====
+
 We should now create your database. For a first local installation, we recommend to start with some example contents (also known as seeds).
 [source,bash]
 ----
@@ -124,11 +125,6 @@ bin/rails db:create db:migrate
 bin/rails db:seed
 ----
 
-[NOTE]
-====
-Please refer to xref:install:empty-database.adoc[Empty database installation] section if you want to setup your instance on an empty database (without any seeds)
-====
-
 This will also create some default data so you can start testing the app, with an administrator account with email admin@example.org and password `decidim123456789`
 
 == 7. Start your web server
@@ -149,12 +145,12 @@ With these steps you would only have an initial installation for trying Decidim,
 
 == Extra notes
 
-Other user accounts that you'll have in the seeds are:
+Other user accounts that you will have in the seeds are:
 
 * To participate as a regular user, with email `user@example.org` and password `decidim123456789`.
 * To manage the Multitenant and being able to log in at `/system`, with email `system@example.org` and password `decidim123456789`.
 
-The seed data won't be created in production environments, if you still want to do it (for instance, for a Demo or Staging server), run:
+The seed data will not be created in production environments, if you still want to do it (for instance, for a Demo or Staging server), run:
 
 [source,bash]
 ----

data/docs/modules/install/pages/update.adoc

@@ -10,7 +10,6 @@ To keep our system up to date, we can visit the page https://github.com/decidim/
 ----
 gem "decidim", "0.20.1"
 gem "decidim-conferences", "0.20.1"
-gem "decidim-consultations", "0.20.1"
 gem "decidim-initiatives", "0.20.1"
 
 gem "decidim-dev", "0.20.1"
@@ -24,7 +23,6 @@ To update, usually requires only to change the old version number on these gems
 ----
 gem "decidim", "0.21"
 gem "decidim-conferences", "0.21"
-gem "decidim-consultations", "0.21"
 gem "decidim-initiatives", "0.21"
 
 gem "decidim-dev", "0.21"
@@ -49,7 +47,6 @@ For managing the gems we use the standard Rails gem called Bundler, where you ca
 ----
 gem "decidim", git: "https://github.com/decidim/decidim", branch: "release/0.22-stable"
 gem "decidim-conferences", git: "https://github.com/decidim/decidim", branch: "release/0.22-stable"
-gem "decidim-consultations", git: "https://github.com/decidim/decidim", branch: "release/0.22-stable"
 gem "decidim-initiatives", git: "https://github.com/decidim/decidim", branch: "release/0.22-stable"
 
 gem "decidim-dev", git: "https://github.com/decidim/decidim", branch: "release/0.22-stable"
@@ -57,7 +54,7 @@ gem "decidim-dev", git: "https://github.com/decidim/decidim", branch: "release/0
 
 == DRY
 
-You can also work with variables in your Gemfile so you can keep it DRY (Don't Repeat Yourself):
+You can also work with variables in your Gemfile so you can keep it DRY (Do not Repeat Yourself):
 
 [source,ruby]
 ----
@@ -65,7 +62,6 @@ DECIDIM_VERSION = "0.21"
 
 gem "decidim", DECIDIM_VERSION
 gem "decidim-conferences", DECIDIM_VERSION
-gem "decidim-consultations", DECIDIM_VERSION
 gem "decidim-initiatives", DECIDIM_VERSION
 
 gem "decidim-dev", DECIDIM_VERSION
@@ -79,17 +75,11 @@ DECIDIM_VERSION = { git: 'https://github.com/decidim/decidim.git', branch: 'rele
 
 gem "decidim", DECIDIM_VERSION
 gem "decidim-conferences", DECIDIM_VERSION
-gem "decidim-consultations", DECIDIM_VERSION
 gem "decidim-initiatives", DECIDIM_VERSION
 
 gem "decidim-dev", DECIDIM_VERSION
 ----
 
-== Compatiblity versions matrix
-
-There are different versions of Decidim that are compatible with different versions of Ruby and Node. You can check the following table to see which versions are compatible with each other:
-
-include::install:partial$version_matrix.adoc[]
 
 [discrete]
 == Recommendations

data/docs/modules/services/pages/activejob.adoc

@@ -2,6 +2,6 @@
 
 For some kind of actions to work on production (for instance, sending emails on user registration) you need to configure an http://edgeguides.rubyonrails.org/active_job_basics.html[ActiveJob] backend on your application.
 
-If you don't want to introduce any other external dependencies for `decidim` (such as `redis`), you can use the `delayed_job` backend. That setup only depends on an underlying database which is already a requirement for `decidim` to work. Add the https://github.com/collectiveidea/delayed_job/[delayed_job] gem to your `Gemfile` and follow the instructions in its readme to set it up.
+If you do not want to introduce any other external dependencies for `decidim` (such as `redis`), you can use the `delayed_job` backend. That setup only depends on an underlying database which is already a requirement for `decidim` to work. Add the https://github.com/collectiveidea/delayed_job/[delayed_job] gem to your `Gemfile` and follow the instructions in its readme to set it up.
 
 However, Decidim is agnostic on which kind of backend do you use, so feel free to set up the backend (ie `sidekiq`, `resque`, etc) you like the most.

data/docs/modules/services/pages/activestorage.adoc

@@ -0,0 +1,94 @@
+= ActiveStorage
+
+Decidim uses https://edgeguides.rubyonrails.org/active_storage_overview.html[ActiveStorage] as the backend to store any user uploaded content. This allows Decidim implementers to easily plug Decidim to different kinds of storage APIs, such as Amazon S3, Google Cloud Storage or Azure Storage. By default, the user uploaded content will be stored to the same file disk where the Decidim application is running at. The default behavior may be problematic with some PaaS providers, such as Heroku.
+
+In order to plug Decidim into a storage provider of your choice, you need to generate the Decidim application using the `--storage` modifier as explained at the xref:configure:index.adoc[configuration guide]. You will also need to provide the correct configuration options for the selected storage provider as explained at the xref:configure:environment_variables.adoc[environment variables guide].
+
+== Dynamic file uploads
+
+Decidim allows participants to upload files dynamically from their browsers to the website using the upload modals where participants can drag and drop the files to or select them from their computer. With the default configuration using a local file storage, this feature does not require any additional configuration. With external storage providers, you have to configure those storages properly to support the client-side file uploads to Decidim.
+
+In order to make the dynamic client-side uploads work with external storage providers, you also need to configure the CORS policies correctly. Example configurations for different storage providers are provided in the following sections which are based on the https://edgeguides.rubyonrails.org/active_storage_overview.html#cross-origin-resource-sharing-cors-configuration[official Rails documentation].
+
+=== Amazon S3
+
+Locate the bucket, go into the "Permissions" tab and find the section titled "CORS" from there. Edit the "CORS" settings and add the following configuration options to the editable field (replace `https://www.example.com` with the actual domain of your service):
+
+
+[source,json]
+----
+[
+  {
+    "AllowedHeaders": [
+      "*"
+    ],
+    "AllowedMethods": [
+      "PUT"
+    ],
+    "AllowedOrigins": [
+      "https://www.example.com"
+    ],
+    "ExposeHeaders": [
+      "Origin",
+      "Content-Type",
+      "Content-MD5",
+      "Content-Disposition"
+    ],
+    "MaxAgeSeconds": 3600
+  }
+]
+----
+
+Read more at https://docs.aws.amazon.com/AmazonS3/latest/userguide/cors.html[Amazon S3 CORS documentation].
+
+===  Google Cloud Storage
+
+Google Cloud Storage requires you to use the `gsutil` command line tool to set the CORS policy on your bucket. First you need to know the name of your bucket and then use the following command (replace `your-bucket-name` with the actual name of the bucket):
+
+[source,bash]
+----
+gsutil cors set cors.json gs://your-bucket-name
+----
+
+Before running that command you need to have a `cors.json` file in the same directory where you are runnign the command from with the following content (replace `https://www.example.com` with the actual domain of your service):
+
+[source,json]
+----
+[
+  {
+    "origin": ["https://www.example.com"],
+    "method": ["PUT"],
+    "responseHeader": ["Origin", "Content-Type", "Content-MD5", "Content-Disposition"],
+    "maxAgeSeconds": 3600
+  }
+]
+----
+
+Read more at https://cloud.google.com/storage/docs/configuring-cors[Google Cloud Storage CORS documentation].
+
+=== Azure Storage
+
+Locate the storage account from the Azure Portal and go to the "Resource sharing (CORS)" section under "Settings. Fill in the following configuration options in the "Blob service" tab of that section (replace `https://www.example.com` with the actual domain of your service):
+
+- **Allowed origins**: https://www.example.com
+- **Allowed methods**: PUT
+- **Allowed headers**: *
+- **Exposed headers**: Origin, Content-Type, Content-MD5, x-ms-blob-content-disposition, x-ms-blob-type
+- **Max age**: 3600
+
+When using the Azure REST API, you can use the `Set Blob Service Properties` operation with the following rule definitions to achieve the same (replace `https://www.example.com` with the actual domain of your service):
+
+[source,xml]
+----
+<Cors>
+  <CorsRule>
+    <AllowedOrigins>https://www.example.com</AllowedOrigins>
+    <AllowedMethods>PUT</AllowedMethods>
+    <AllowedHeaders>*</AllowedHeaders>
+    <ExposedHeaders>Origin, Content-Type, Content-MD5, x-ms-blob-content-disposition, x-ms-blob-type</ExposedHeaders>
+    <MaxAgeInSeconds>3600</MaxAgeInSeconds>
+  </CorsRule>
+</Cors>
+----
+
+Read more at https://docs.microsoft.com/en-us/rest/api/storageservices/cross-origin-resource-sharing--cors--support-for-the-azure-storage-services[Azure Storage CORS documentation].

data/docs/modules/services/pages/elections_bulletin_board.adoc

@@ -7,7 +7,7 @@ This is a work in progress and is not fully working yet.
 
 In order to celebrate https://en.wikipedia.org/wiki/End-to-end_auditable_voting_systems[End-to-end auditable votings] using the Elections module, you will need to connect your Decidim instance with an instance of the https://github.com/decidim/decidim-bulletin-board/[Decidim Bulletin Board application].
 
-*Note*: The connected Bulletin Board instance is used by all organizations, therefore it's recommended to set it up by an independent organization.
+*Note*: The connected Bulletin Board instance is used by all organizations, therefore it is recommended to set it up by an independent organization.
 
 == Identification pair of keys generation
 

data/docs/modules/services/pages/etherpad.adoc

@@ -50,6 +50,6 @@ To better understand this feature, the final idea is to have the three moments o
 * *During the meeting*, notes can be taken on a collaborative way
 * *After the meeting*, you upload the notes, minutes, metadata and/or pictures to have a record on what was discussed
 
-Pad creation can be enabled by administrators in each `Meetings` component. When enabled, the public view of a Meeting renders an iframe which encapsulates the integrated Pad. This Pad is automatically created before rendering, so there's nothing the user or the administrators has to do to see the Pad.
+Pad creation can be enabled by administrators in each `Meetings` component. When enabled, the public view of a Meeting renders an iframe which encapsulates the integrated Pad. This Pad is automatically created before rendering, so there is nothing the user or the administrators has to do to see the Pad.
 
 The pad iframe is only accessible for 24 hours before and 72 hours after the meeting. After the meeting only the read only URL for this pad is shown.

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

@@ -1,8 +1,9 @@
 = Services
 
-There are multiple services that can be enabled in a Decidim installation. It's important to note that the only mandatory services are the xref:services:activejob.adoc[Active Job] queue and the xref:services:smtp.adoc[SMTP] server. The others are optional and depend on your specific usecase.
+There are multiple services that can be enabled in a Decidim installation. It is important to note that the only mandatory services are the xref:services:activejob.adoc[Active Job] queue and the xref:services:smtp.adoc[SMTP] server. The others are optional and depend on your specific usecase.
 
 * xref:services:activejob.adoc[Active Job]
+* xref:services:activestorage.adoc[Active Storage]
 * xref:services:elections_bulletin_board.adoc[Elections Bulletin Board]
 * xref:services:etherpad.adoc[Etherpad]
 * xref:services:maps.adoc[Maps]

data/docs/modules/services/pages/maps.adoc

@@ -17,7 +17,7 @@ Decidim has built-in support for the following map service providers:
  ** <<configuring-here-maps,Configuring HERE Maps>>
 * https://wiki.openstreetmap.org/wiki/Commercial_OSM_Software_and_Services[Open Street Maps based services]
  ** Please pick a service provider that provides all needed services (map tiles, static map images, geocoding and geocoding autocompletion)
- ** We can't use the OSM's own services by their https://operations.osmfoundation.org/policies/tiles/[tile usage policy].
+ ** We cannot use the OSM's own services by their https://operations.osmfoundation.org/policies/tiles/[tile usage policy].
  ** In case your service provider does not offer static map images, Decidim will use the dynamic map tiles to generate a similar map element.
  ** As an alternative, you may also want to use your own self-hosted map servers (see <<hosting-your-own-map-services,Hosting your own map services>> for more information)
  ** <<configuring-open-street-maps-based-service-providers,Configuring Open Street Maps based service providers>>
@@ -26,7 +26,7 @@ If you want to integrate Decidim to some other map service provider, read how to
 
 == Configuring maps and geocoding
 
-After generating your app, you'll see that your `config/initializers/decidim.rb` file includes commented code about map services:
+After generating your app, you will see that your `config/initializers/decidim.rb` file includes commented code about map services:
 
 [source,ruby]
 ----
@@ -78,6 +78,7 @@ default: &default
 
 [source,bash]
 ----
+MAPS_PROVIDER=here
 MAPS_API_KEY=your_api_key_here
 ----
 
@@ -235,12 +236,12 @@ If you want to integrate the map functionality with a new service provider, take
 
 == Enabling maps and geocoding
 
-Once the maps functionality is configured, you'll need to activate it.
+Once the maps functionality is configured, you will need to activate it.
 As of April 2017, only proposals and meetings have maps and geocoding.
 
 === Proposals
 
-In order to enable geocoding for proposals you'll need to edit the component configuration and turn on "Geocoding enabled" configuration.
+In order to enable geocoding for proposals you will need to edit the component configuration and turn on "Geocoding enabled" configuration.
 This works for that specific component, so you can have geocoding enabled for proposals in a participatory process, and disabled for another proposals component in the same participatory process.
 
 === Meetings

data/docs/modules/services/pages/sms.adoc

@@ -9,10 +9,11 @@ An example class would be something like:
 [source,ruby]
 ....
 class MySMSGatewayService
-  attr_reader :mobile_phone_number, :code
-  def initialize(mobile_phone_number, code)
+  attr_reader :mobile_phone_number, :code, :context
+  def initialize(mobile_phone_number, code, context = {})
     @mobile_phone_number = mobile_phone_number
     @code = code
+    @context = context
   end
   def deliver_code
     # Actual code to deliver the code
@@ -21,7 +22,13 @@ class MySMSGatewayService
 end
 ....
 
-Then you'll need to configure it in the Decidim initializer:
+The arguments provided for the initialize method are:
+
+- `mobile_phone_number` - The full mobile phone number to send the message to, containing the country code.
+- `code` - The code or the message to be sent to the given mobile phone number.
+- `context` - An extra context attribute which can be used to pass e.g. the correct organization for the gateway to utilize.
+
+Then you will need to configure it in the Decidim initializer:
 
 [source,ruby]
 ....
@@ -30,3 +37,5 @@ Then you'll need to configure it in the Decidim initializer:
 
 You can find an example on how this is set up at https://github.com/AjuntamentdeBarcelona/decidim-barcelona/blob/672f5a8938d884940899b4304f0a17e25d42d2a0/app/services/sms_gateway.rb[DecidimBarcelona's app/services/sms_gateway.rb]. Your final implementation will depend on how your SMS provider works.
 
+Another example which also utilizes the `context` argument can be found from the Twilio SMS integration available at:
+https://github.com/Pipeline-to-Power/decidim-module-ptp/blob/aa82286d91d404e83ea16a55d281a1b049bbaca2/decidim-sms-twilio/lib/decidim/sms/twilio/gateway.rb

data/docs/modules/services/pages/social_providers.adoc

@@ -63,14 +63,14 @@ To create a new OAuth application in the OAuth provider Decidim installation you
 * Name: The name of the client application that will be shown to the user when authorizing it from your Decidim application.
 * Redirect URI: The URI where the Decidim application should redirect the user after authorizing it.
 It is usually where you handle the OAUth callback in your client application.
-If you're using `omniauth-decidim` the value should be `YOUR_APPLICATION_HOST/users/auth/decidim/callback`.
+If you are using `omniauth-decidim` the value should be `YOUR_APPLICATION_HOST/users/auth/decidim/callback`.
 * Organization name: The name of the organization that owns the client application.
 * Organization URL: The URL of the organization that owns the client application.
 * Organization logo: An image of the logo of the organization that owns the client application.
 
-All the organization data will be used during the authorization process so the users know to who they're giving their data.
+All the organization data will be used during the authorization process so the users know to who they are giving their data.
 
-Once you've created your application you'll get the settings to setup your clients.
+Once you have created your application you will get the settings to setup your clients.
 
 Instructions in how to configure the client applications can be found in the module's https://github.com/decidim/omniauth-decidim#usage[usage section].