decidim 0.24.3 → 0.25.0.rc4

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

@@ -0,0 +1,175 @@
+= Migrate to Webpacker an instance app
+
+In order to migrate an existing Decidim app to Webpacker, there are a few changes your need to run in your code.
+
+Disclaimer: this recipe might not work for all the cases, it tries to cover the generic scenarios. If you find yourself with a complex scenario and want to improve this guide feel free to open a PR to complete the guide.
+
+== About Webpacker
+
+It's recommended to understand how Webpacker works. More information:
+
+* https://github.com/rails/webpacker#usage
+* https://edgeguides.rubyonrails.org/webpacker.html
+
+== Requirements
+
+Before starting the migration, please check you have the following dependencies installed:
+
+- Node.js version 16.9.x (this version is mandatory)
+- Npm version 7.21.x (it works with other versions, but this is the recommended)
+
+== Add Webpacker to the application
+
+Follow the steps described https://github.com/rails/webpacker#installation[here]
+
+- Install it
+
+[source,console]
+----
+bundle exec rails webpacker:install
+----
+
+* Install Decidim webpacker custom code
+
+[source,console]
+----
+bundle exec rails decidim:webpacker:install
+----
+
+This task do a few steps to allow the Rails instance to have a webpacker instance sharing the code between itself and Decidim gem.
+
+This task is automatically performed every time decidim is updated, to get the latest Webpack configuration. This happens when you run the `decidim:upgrade` task.
+
+== Copy Decidim custom CSS and Javascript
+
+`webpacker:install` task should have created to you the following dirs structure:
+
+[source,console]
+----
+app/packs:
+  ├── entrypoints
+  └── src
+  └── stylesheets
+  └── images
+----
+
+If it's 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`
+* Copy the file https://github.com/decidim/decidim/blob/develop/decidim-generators/lib/decidim/generators/app_templates/_decidim-settings.scss[_decidim-settings.scss] to `app/packs/stylesheets/decidim/_decidim-settings.scss`
+
+These files are hooked into Decidim packs (specifically into decidim-core pack) and will be automatically included inside that pack when compiled.
+
+== Migrate images
+
+Copy the existing images from `app/assets/images` to `app/packs/images`. Images will be available at `/media/images/image.png`
+
+== Migrate stylesheets
+
+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 any of the CSS is re-defining CSS vars add them to `_decidim-settings.scss`.
+
+== Migrate javascripts
+
+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`
+
+== Update Rails helpers
+
+`javascript_include_tag` and `stylesheet_link_tag` have been replaced by `javascript_pack_tag` and `stylesheet_pack_tag`.
+
+For images, if they are in `app/packs/images` you could use `image_pack_tag`.
+
+== Migrate vendorized files and gems
+
+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.
+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.
+
+== Optional asset includes
+
+Decidim Webpacker provides a new configuration convention that allows you to add extra configurations for webpacker using a configuration file named `config/assets.rb`. Within this file, you have the following API methods available:
+
+[source,ruby]
+----
+# frozen_string_literal: true
+# This file is located at `config/assets.rb` of your module.
+
+# Define the base path of your module. Please note that `Rails.root` may not be
+# used because we are not inside the Rails environment when this file is loaded.
+base_path = File.expand_path("..", __dir__)
+
+# If you want to import some extra SCSS files in the Decidim main SCSS file
+# without adding any extra stylesheet inclusion tags, you can use the following
+# method to register the stylesheet import for the main application. This would
+# include an SCSS file at `app/packs/stylesheets/your_app_extensions.scss` into
+# the Decidim's main SCSS file.
+Decidim::Webpacker.register_stylesheet_import("stylesheets/your_app_extensions")
+
+# If you want to do the same but include the SCSS file for the admin panel's
+# main SCSS file, you can use the following method.
+Decidim::Webpacker.register_stylesheet_import("stylesheets/your_app_admin_extensions", group: :admin)
+----
+
+== Remove Sprockets references
+
+The completely remove Sprockets references from your application:
+
+* Review your Gemfile and remove any reference to `sprockets` and `sassc-rails`
+* Remove `config/initializers/assets.rb`
+* Remove `app/assets` folder
+* In `config/application.rb` replace:
+
+[source,ruby]
+----
+require 'rails/all'
+----
+
+with:
+
+[source,ruby]
+----
+require "decidim/rails"
+# Add the frameworks used by your app that are not loaded by Decidim.
+# require "action_cable/engine"
+# require "action_mailbox/engine"
+# require "action_text/engine"
+----
+
+* In `config/environments/*.rb` remove any line containing `config.assets.*` (i.e `config.assets.debug = true`)
+
+== Deployment
+
+The deployment needs to be updated to manually run `npm install` before assets are precompiled.
+
+In the case of Capistrano this can be done with a before hook:
+
+[source,ruby]
+----
+namespace :deploy do
+  desc "Decidim webpacker configuration"
+  task :decidim_webpacker_install do
+    on roles(:all) do
+      within release_path do
+        with rails_env: fetch(:rails_env) do
+          execute "npm ci"
+        end
+      end
+    end
+  end
+
+  before "deploy:assets:precompile", "deploy:decidim_webpacker_install"
+end
+----
+
+Also, in the case of Capistrano it's interesting to add to the shared_paths the following folders:
+
+* `tmp/webpacker-cache`
+* `node_modules`
+* `public/decidim-packs`

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

@@ -0,0 +1,121 @@
+= Migrate to Webpacker a Decidim module
+
+Decidim modules are included to Decidim apps as gems. Since the introduction of Webpacker to manage and compile assets in Decidim, there are some changes required to make modules compatible with Decidim
+
+== About Webpacker
+
+It's recommended to understand how Webpacker works. More information:
+
+* https://github.com/rails/webpacker#usage
+* https://edgeguides.rubyonrails.org/webpacker.html
+
+== Overview
+
+The recommended way to import assets from a gem in a Rails app using Webpacker is to publish a package in npmjs.org and include it in the package.json via `npm install`. Then the assets are available to Webpack via node_modules/ folder
+
+Once created, you should update the instructions to install the module and add the step to add the assets with npm.
+
+== Folder migration
+
+It's recommend to migrate to the new folders structure:
+
+```
+app/packs:
+  ├── entrypoints
+  └── src
+  └── stylesheets
+  └── images
+```
+
+== Update Rails helpers
+
+`javascript_include_tag` and `stylesheet_link_tag` have been replaced by `javascript_pack_tag` and `stylesheet_pack_tag`
+
+For images, if they are in `app/packs/images` you could use `image_pack_tag`.
+
+== Asset compilation
+
+As all assets are now compiled using Webpacker without ever loading the Rails or Decidim environment, there are some new conventions how to tell Webpacker about the Decidim module's assets.
+
+To begin with, create a new file named `config/assets.rb` inside your Decidim module.
+
+After this, add the following contents in that file, depending what kind of assets your module provides:
+
+[source,ruby]
+----
+# frozen_string_literal: true
+# This file is located at `config/assets.rb` of your module.
+
+# Define the base path of your module. Please note that `Rails.root` may not be
+# used because we are not inside the Rails environment when this file is loaded.
+base_path = File.expand_path("..", __dir__)
+
+# Register an additional load path for webpack. All the assets within these
+# directories will be available for inclusion within the Decidim assets. For
+# example, if you have `app/packs/src/decidim/foo.js`, you can include that file
+# in your JavaScript entrypoints (or other JavaScript files within Decidim)
+# using `import "src/decidim/foo"` after you have registered the additional path
+# as follows.
+Decidim::Webpacker.register_path("#{base_path}/app/packs")
+
+# Register the entrypoints for your module. These entrypoints can be included
+# within your application using `javascript_pack_tag` and if you include any
+# SCSS files within the entrypoints, they become available for inclusion using
+# `stylesheet_pack_tag`.
+Decidim::Webpacker.register_entrypoints(
+  decidim_foo: "#{base_path}/app/packs/entrypoints/decidim_foo.js",
+  decidim_foo_admin: "#{base_path}/app/packs/entrypoints/decidim_foo_admin.js"
+)
+
+# If you want to import some extra SCSS files in the Decidim main SCSS file
+# without adding any extra stylesheet inclusion tags, you can use the following
+# method to register the stylesheet import for the main application.
+Decidim::Webpacker.register_stylesheet_import("stylesheets/decidim/foo/app")
+
+# If you want to do the same but include the SCSS file for the admin panel's
+# main SCSS file, you can use the following method.
+Decidim::Webpacker.register_stylesheet_import("stylesheets/decidim/foo/admin", group: :admin)
+
+# If you want to override some SCSS variables/settings for Foundation from the
+# module, you can add the following registered import.
+Decidim::Webpacker.register_stylesheet_import("stylesheets/decidim/foo/settings", type: :settings)
+
+# If you want to do the same but override the SCSS variables of the admin
+# panel's styles, you can use the following method.
+Decidim::Webpacker.register_stylesheet_import("stylesheets/decidim/foo/admin_settings", type: :settings, group: :admin)
+----
+
+== Component stylesheet migration
+
+In older Decidim versions your components could define their own stylesheet as follows:
+
+[source,ruby]
+----
+Decidim.register_component(:your_component) do |component|
+  component.engine = Decidim::YourComponent::Engine
+  component.stylesheet = "decidim/your_component/your_component"
+  component.admin_stylesheet = "decidim/your_component/your_component_admin"
+end
+----
+
+These were automatically included in the main application's stylesheet file and also in the admin panel's stylesheet file. These no longer work with Webpacker as the Decidim environment is not loaded when Webpacker compiles the assets.
+
+What you should do instead is to follow the asset compilation migration guide above and migrate these definitions into your module's `config/assets.rb` file as follows:
+
+[source,ruby]
+----
+# frozen_string_literal: true
+# This file is located at `config/assets.rb` of your module.
+
+base_path = File.expand_path("..", __dir__)
+
+# Register the additonal path for Webpacker in order to make the module's
+# stylesheets available for inclusion.
+Decidim::Webpacker.register_path("#{base_path}/app/packs")
+
+# Register the main application's stylesheet include statement:
+Decidim::Webpacker.register_stylesheet_import("stylesheets/decidim/your_component/your_component")
+
+# Register the admin panel's stylesheet include statement:
+Decidim::Webpacker.register_stylesheet_import("stylesheets/decidim/your_component/your_component_admin", group: :admin)
+----

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

@@ -186,7 +186,7 @@ module Decidim
           # autocompletion functionality in the front-end:
           class Builder < Decidim::Map::Autocomplete::Builder
             def javascript_snippets
-              template.javascript_include_tag("decidim/geocoding/provider/your_provider")
+              template.javascript_pack_tag("decidim/geocoding/provider/your_provider")
             end
           end
         end
@@ -196,7 +196,7 @@ module Decidim
 end
 ----
 
-To see an example of the front-end JavaScript code that handles the geocoding requests, you can take a look at the link:/decidim-core/app/assets/javascripts/decidim/geocoding/provider/here.js.es6[HERE Maps example].
+To see an example of the front-end JavaScript code that handles the geocoding requests, you can take a look at the link:/decidim-core/app/packs/src/decidim/geocoding/provider/here.js.es6[HERE Maps example].
 You will have to listen to the `geocoder-suggest.decidim` JavaScript event on all elements that have the `data-decidim-geocoding` attribute defined which contains all the configurations returned by the builder's `builder_options` method as mentioned above.
 For example, if you passed the following configuration from that method:
 

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

@@ -19,7 +19,7 @@ Decidim.content_blocks.register(:newsletter_template, :my_template) do |content_
     {
       name: :main_image,
       uploader: "Decidim::NewsletterTemplateImageUploader",
-      preview: -> { ActionController::Base.helpers.asset_path("decidim/placeholder.jpg") }
+      preview: -> { ActionController::Base.helpers.asset_pack_path("media/images/placeholder.jpg") }
     }
   ]
 

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

@@ -74,9 +74,11 @@ Running it as is, or passing it the `--help` flag, will render the help section
 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 output of the command to the relevant sections of the changelog file.
+You can copy-paste the contents of the temporary changelog file to the relevant sections of the Changelog file.
 
 == Release Candidates
 

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

@@ -47,3 +47,14 @@ bundle exec rake test_all
 ----
 
 But beware, it takes a long time... :)
+
+== Continuous integration
+
+The tests are also run when a new commit is added to the `develop` or releases
+branches, or added to a Pull Request. In the latter case, only the tests for
+the modules affected by any the PR commits will be executed.
+
+This means that the workflows defined for each module in the folder
+`.github/workflows/` should be always updated with the module's dependencies
+list. The script `.github/workflows/dependencies.sh` can be helpful to keep
+those files updated until we have an automatic process to do it.

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

@@ -29,21 +29,10 @@ The `label` option accepts this arguments:
 
 == Introducing a Card Cell to a `component`
 
-* add *dependency* to "decidim-*.gemspec"
+* Add the module cell paths to cell view paths in `decidim-<module>/lib/decidim/<module>/engine.rb`
 +
 [source,rb]
 ----
-s.add_dependency "cells-erb", "~> 0.1.0"
-s.add_dependency "cells-rails", "~> 0.0.9"
-----
-
-* *require* cells in `decidim-<module>/lib/decidim/<module>/engine.rb`
-+
-[source,rb]
-----
-require "cells/rails"
-require "cells-erb"
-
 initializer "decidim_<module>.add_cells_view_paths" do
   Cell::ViewModel.view_paths << File.expand_path("#{Decidim::<Module>::Engine.root}/app/cells")
   Cell::ViewModel.view_paths << File.expand_path("#{Decidim::<Module>::Engine.root}/app/views") # for partials

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

@@ -1,40 +1,39 @@
 = Manual installation tutorial
 
-== Step by step
-
 In order to develop on decidim, you'll need:
 
 * *Git* 2.15+
-* *PostgreSQL* 9.5+
-* *Ruby* 2.5.0 (2.3+ should work just fine, but that's the version we test against)
-* *NodeJS* 9.x.x
+* *PostgreSQL* 12.7+
+* *Ruby* 2.7.1
+* *NodeJS* 16.9.x
+* *Npm* 7.21.x
 * *ImageMagick*
 * *Chrome* browser and https://sites.google.com/a/chromium.org/chromedriver/[chromedriver].
 
-We're starting with an Ubuntu 16.04 LTS. This is an opinionated guide and YMMV, so if you're free to use the technology that you fell most comfortable on. If you have any doubts and you're blocked you can go and ask on https://gitter.im/decidim/decidim[our Gitter]. We recommend that you follow some Ruby on Rails tutorials (like http://guides.rubyonrails.org/getting_started.html[Getting Started with Ruby on Rails]) and have some knowledge on how gems and engines work.
+We're starting with an Ubuntu 20.04 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://gitter.im/decidim/decidim[our Gitter].
+
+We recommend to have at least some basic proficiency in Ruby on Rails (a good starting point is http://guides.rubyonrails.org/getting_started.html[Getting Started with Ruby on Rails]) and have some knowledge on how gems work.
 
-On this tutorial we'll see how to install rbenv, PostgreSQL and Decidim, and how to configure everything together.
+In this guide, we'll see how to install rbenv, PostgreSQL and, Decidim, and how to configure everything together.
 
-=== Installing rbenv
+== 1. Installing rbenv
 
-First we're going to install rbenv, for managing various ruby versions. We're following the guide from https://www.digitalocean.com/community/tutorials/how-to-install-ruby-on-rails-with-rbenv-on-ubuntu-16-04[DigitalOcean]. You could also use https://rvm.io/[rvm] as an alternative on this step. On these instruction we're using the latest ruby published version at the moment (2.5.3), but you should check this out on https://www.ruby-lang.org/en/downloads/[Ruby official website].
+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. Mind that at the moment, Decidim isn't compatible with Ruby 3.0.
 
 [source,bash]
 ----
 sudo apt update
-sudo apt install -y build-essential autoconf bison libssl-dev libyaml-dev libreadline-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm3 libgdbm-dev libicu-dev
+sudo apt install -y build-essential git libssl-dev zlib1g-dev
 git clone https://github.com/rbenv/rbenv.git ~/.rbenv
 echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
 echo 'eval "$(rbenv init -)"' >> ~/.bashrc
 source ~/.bashrc
 git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
-rbenv install 2.5.3
-rbenv global 2.5.3
-echo "gem: --no-document" > ~/.gemrc
-gem install bundler
+rbenv install 2.7.1
+rbenv global 2.7.1
 ----
 
-=== Installing PostgreSQL
+== 2. Installing PostgreSQL
 
 Now we're going to install PostgreSQL for the database:
 
@@ -44,20 +43,19 @@ sudo apt install -y postgresql libpq-dev
 sudo -u postgres psql -c "CREATE USER decidim_app WITH SUPERUSER CREATEDB NOCREATEROLE PASSWORD 'thepassword'"
 ----
 
-You need to change the password (on this example is "thepassword") and save it somewhere to configure it later with the application.
+You need to change the password (in this example is "thepassword") and save it somewhere to configure it later with the application.
 
-=== Installing Decidim
+== 3. Installing Decidim
 
-Next, we need to install the `decidim` gem:
+Next, we need to install the `decidim` gem with its dependencies:
 
 [source,bash]
 ----
-gem install bootsnap
-gem install listen
+sudo apt install -y libicu-dev nodejs imagemagick
 gem install decidim
 ----
 
-Afterwards, we can create an application with the nice `decidim` executable, where `decidim_application` is your application name (ie decidim.barcelona):
+Then we can create an application with the `decidim` executable, where `decidim_application` is your application name (ie DecidimBarcelona):
 
 [source,bash]
 ----
@@ -69,13 +67,13 @@ We recommend that you save it all on Git.
 
 [source,bash]
 ----
-git init .
-git commit -m "Initial commit. Generated with Decidim 0.X https://decidim.org"
+git add .
+git commit -m "Initial commit. Generated with Decidim https://decidim.org"
 ----
 
-=== Configure the database
+== 4. Configure the database
 
-You need to 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.
+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.
 
 For instance, for working with figaro, add this to your `Gemfile`:
 
@@ -92,13 +90,13 @@ bundle install
 bundle exec figaro install
 ----
 
-Next add this to your `config/application.yml`, using the setup the PostgreSQL database name, user and password that you configure before.
+Next, add this to your `config/application.yml`, using the setup PostgreSQL database name, user and, password that you've configured before.
 
 [source,yaml]
 ----
 DATABASE_HOST: localhost
 DATABASE_USERNAME: decidim_app
-DATABASE_PASSWORD: your_password
+DATABASE_PASSWORD: thepassword
 ----
 
 Finally, save it all to git:
@@ -106,12 +104,12 @@ Finally, save it all to git:
 [source,bash]
 ----
 git add .
-git commit -m "Adds figaro configuration management"
+git commit -m "Add figaro configuration management"
 ----
 
-=== Initializing your app for local development
+== 5. Initializing your app for local development
 
-We should now setup your database:
+We should now create your database:
 
 [source,bash]
 ----
@@ -119,29 +117,34 @@ bin/rails db:create db:migrate
 bin/rails db:seed
 ----
 
-This will also create some default data so you can start testing the app:
+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 `decidim123456`
 
-* A `Decidim::System::Admin` with email `system@example.org` and password `decidim123456`, to log in at `/system`.
-* A `Decidim::Organization` named `Decidim Staging`. You probably want to change its name and hostname to match your needs.
-* A `Decidim::User` acting as an admin for the organization, with email `admin@example.org` and password `decidim123456`.
-* A `Decidim::User` that also belongs to the organization but it's a regular user, with email `user@example.org` and password `decidim123456`.
+== 6. Start your web server
 
-This data won't be created in production environments, if you still want to do it, run:
+You can now start your server!
 
 [source,bash]
 ----
-SEED=true rails db:setup
+bin/rails s
 ----
 
-==== Notes
+Visit http://localhost:3000 to see your app running. 🎉 🎉
 
-When you run `bin/rails db:migrate` you should see a lot of output. If you don't, or if you run into errors seeding your database, try runnning `bin/rake decidim:upgrade` before.
+[NOTE]
+====
+With these steps you would only have an initial installation for trying Decidim, but it still needs lots of things to take in account. If you want a working production system then we recommend that you follow the https://platoniq.github.io/decidim-install/[Decidim Install guide by Platoniq].
+====
 
-You can now start your server!
+== Extra notes
+
+Other user accounts that you'll have in the seeds are:
+
+* To participate as a regular user, with email `user@example.org` and password `decidim123456`.
+* To manage the Multitenant and being able to log in at `/system`, with email `system@example.org` and password `decidim123456`.
+
+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:
 
 [source,bash]
 ----
-bin/rails s
+SEED=true rails db:seed
 ----
-
-Visit http://localhost:3000 to see your app running. 🎉 🎉

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

@@ -5,11 +5,13 @@
 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], preferably run by an independent organization.
+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.
 
 == Identification pair of keys generation
 
-The first step needed to setup the connection is to generate an a pair of keys to identify the application against the Bulletin Board.
+The first step needed to setup the connection is to generate a pair of keys to identify the application against the Bulletin Board.
 This can be done running the following rake task in your application environment:
 
 [source,sh]
@@ -17,32 +19,33 @@ This can be done running the following rake task in your application environment
 bundle exec rake decidim_elections:generate_identification_keys
 ----
 
-This task will output the generated private and public keys. You should copy the public key and send it to the Bulletin Board administrator through a secure channel. Together with the key, send your *Authority name* to the Bulletin Board administrator and store its value on the environment variable `BULLETIN_BOARD_AUTHORITY_NAME`.
+This task will output the generated private and public keys. You should copy the public key and send it, together with your *Authority name* to the Bulletin Board administrator through a secure channel. Together with the key, send your *Authority name* to the Bulletin Board administrator.
+
+After that, copy the private key and store that value on the environment variable `AUTHORITY_PRIVATE_KEY` and your *Authority name* on the variable `AUTHORITY_NAME`.
 
-After that, copy the private key and store that value on the environment variable `BULLETIN_BOARD_IDENTIFICATION_PRIVATE_KEY`.
+Ensure that the private key is not lost between deployments and servers reboots and that it can only be accessed by the application.
 
-Ensure that the private key is not lost between deployments and servers reboots and that only can be accessed by the application.
+As an administrator of the Bulletin Board, you find the steps to be taken https://github.com/decidim/decidim-bulletin-board/blob/develop/decidim-bulletin_board-app/docs/setup.md#adding-an-authority-as-a-client-of-the-bulletin-board[here].
 
 == Configuration of the Bulletin Board application
 
 The Bulletin Board administrator will store the received public key in their server and will send you back an API key.
-To complete the setup process you should store this API key and the Bulletin Board URL address on the environment variables `BULLETIN_BOARD_API_KEY` and `BULLETIN_BOARD_SERVER`, respectively.
+To complete the setup process you should store this API key and the Bulletin Board URL address on the environment variables `AUTHORITY_API_KEY` and `BULLETIN_BOARD_SERVER`, respectively.
 
 The following YAML snippet with all the defined environment variables should be used in the `default` block of your application `config/secrets.yml` file.
 Maybe this is already done, as it was included in the Decidim applications generator during the development of the Elections module.
 
 [source,yaml]
 ----
-  bulletin_board:
-    identification_private_key: <%= ENV["BULLETIN_BOARD_IDENTIFICATION_PRIVATE_KEY"] %>
-    server: <%= ENV["BULLETIN_BOARD_SERVER"] %>
-    api_key: <%= ENV["BULLETIN_BOARD_API_KEY"] %>
-    number_of_trustees: <%= ENV["BULLETIN_BOARD_NUMBER_OF_TRUSTEES"] %>
-    authority_name: <%= ENV["BULLETIN_BOARD_AUTHORITY_NAME"] %>
-    scheme:
-      name: <%= ENV["BULLETIN_BOARD_SCHEME_NAME"] %>
-      parameters:
-        quorum: <%= ENV["BULLETIN_BOARD_SCHEME_QUORUM"] %>
+  elections:
+    bulletin_board_server: <%= ENV["BULLETIN_BOARD_SERVER"] %>
+    bulletin_board_public_key: <%= ENV["BULLETIN_BOARD_PUBLIC_KEY"] %>
+    authority_api_key: <%= ENV["AUTHORITY_API_KEY"] %>
+    authority_name: <%= ENV["AUTHORITY_NAME"] %>
+    authority_private_key: <%= ENV["AUTHORITY_PRIVATE_KEY"] %>
+    scheme_name: <%= ENV["ELECTIONS_SCHEME_NAME"] %>
+    number_of_trustees: <%= ENV["ELECTIONS_NUMBER_OF_TRUSTEES"] %>
+    quorum: <%= ENV["ELECTIONS_QUORUM"] %>
 ----
 
 After restarting the Decidim instance, administrator users will be able to create elections on the configured Bulletin Board.

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

@@ -82,7 +82,7 @@ Instructions in how to configure the client applications can be found in the mod
 * Or you can create a new strategy, as the https://github.com/decidim/omniauth-decidim[Decidim OmniAuth Strategy]. This strategy allow users from a Decidim instance to login in other Decidim instance. For example, this strategy is used to allow https://decidim.barcelona[decidim.barcelona] users to log into https://meta.decidim.barcelona[meta.decidim.barcelona].
 * Once you have defined your strategy, you can configure it in the `config/secrets.yml` or in the organization configuration, as it is done for the built-in providers.
 * By default, Decidim will search in its icons library for an icon named as the provider. You can change this adding an `icon` or `icon_path` attribute to the provider configuration. The `icon` attribute sets the icon name to look for in the Decidim's icons library. The `icon_path` attribute sets the route to the image that should be used.
-* Here is an example of the configuration section for the Decidim strategy, using an icon located on the application's `app/assets/images` folder:
+* Here is an example of the configuration section for the Decidim strategy, using an icon located on the application's `app/packs/images` folder:
 
 [source,yaml]
 ----