decidim 0.25.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4b9922e88de129b511673c9ba40958c2afacdcaa07ec038b500af10badf4678
-  data.tar.gz: c7361bb91075206b25d6f737af846350b949971d6ccb4e4d3a4ada591c2631c0
+  metadata.gz: 298209f3c00f41e8f98704545a6c3af1e91a6728d3833a043c94e26d8dba63e3
+  data.tar.gz: 8ef259aa25e52150a0a0eb59c84bf0c3e752fd25df034450e6f3f4f4a2fdb471
 SHA512:
-  metadata.gz: 806beb8e688782393414029fc83af33b50e9cde93a61f2da505473db0300fe768a560588c8b294149849c79c36a4fc31c38fbba3ff17df701440ae3337ad7cd9
-  data.tar.gz: 2dd05493e0d2702c7294e391551df7bafe27f4cd5039656591ac609c9b4f78c968f824076542166ce621a001576e590341519628160389abe4c4d6fe1fc13b1d
+  metadata.gz: '0968d207a94b288467d4754d8394929ba81a4c8e470a44e1525e9abdf3f7604673d114d85b9112a32ffb9e861606c8e84feddfd0e73b3b35cbeb636c59a36514'
+  data.tar.gz: f0aa80e3337e794c1ce0165a4143e5087ce02a9724d9bfc624c90feb8835e097b4ba9147b1b6023833b8ab615b75b8438b3d2dede7f605ec03b4dda2a784885d

data/Rakefile

@@ -68,6 +68,7 @@ task :check_locale_completeness do
 end
 
 load "decidim-dev/lib/tasks/generators.rake"
+load "lib/tasks/common_passwords_tasks.rake"
 
 desc "Generates a dummy app for testing"
 task test_app: "decidim:generate_external_test_app"

data/docs/antora.yml

@@ -1,5 +1,5 @@
 name: en
-title: "Decidim Developers Documentation"
+title: "Decidim Documentation"
 version: master
 asciidoc:
   attributes:

data/docs/modules/customize/pages/authorizations.adoc

@@ -20,3 +20,29 @@ Each decidim instance is in full control of its authorizations, and can customiz
 * The different actions in decidim that require authorization, and which authorization method they require. For example, a decidim instance might choose to require census authorization to create proposals, but a fully verified address via a verification code sent by postal mail for voting on proposals.
 
 See https://github.com/decidim/decidim/blob/develop/decidim-verifications/README.md[decidim-verifications's README] and https://decidim.org/modules[Decidim's Modules page].
+
+== Examples
+
+Here are some examples:
+
+- https://github.com/AjuntamentdeBarcelona/decidim-barcelona/blob/master/app/services/census_authorization_handler.rb[Barcelona (City)]
+- https://github.com/AjuntamentdeCalafell/decidim-calafell/blob/master/app/services/census_authorization_handler.rb[Calafell]
+- https://github.com/diputacioBCN/decidim-diba/blob/master/decidim-diba_census_api/app/services/diba_census_api_authorization_handler.rb[DIBA (Barcelona Province)]
+- https://github.com/AjuntamentDeGava/decidim-gava/blob/master/app/services/census_authorization_handler.rb[Gavà]
+- https://github.com/HospitaletDeLlobregat/decidim-hospitalet/blob/master/app/services/census_authorization_handler.rb[Hospitalet de Llobregat]
+- https://github.com/AjMalgrat/decidim-malgrat/blob/master/app/services/carpetaciutada_handler.rb[Malgrat de Mar]
+- https://github.com/AjuntamentDeMataro/decidimmataro.cat/blob/master/app/services/census_authorization_handler.rb[Mataró]
+- https://github.com/ErabakiPamplona/erabaki/blob/master/app/services/census_authorization_handler.rb[Pamplona]
+- https://github.com/AjuntamentdeReus/decidim/blob/master/app/services/census_authorization_handler.rb[Reus]
+- https://github.com/AjuntamentDeSabadell/decidim-sabadell/blob/master/app/services/census_authorization_handler.rb[Sabadell]
+- https://github.com/AjuntamentdeSantCugat/decidim-sant_cugat/blob/master/app/services/census_authorization_handler.rb[Sant Cugat]
+- https://github.com/AjuntamentDeTerrassa/decidim-terrassa/blob/master/app/services/census_authorization_handler.rb[Terrassa]
+- https://github.com/vilanovailageltru/decidim-vilanova/blob/master/app/services/vilanova_authorization_handler.rb[Vilanova i la Geltrú]
+
+Other special verifications:
+
+- https://github.com/podemos-info/participa2/tree/master/decidim-module-census_connector[Podemos]
+- https://github.com/ElectricThings/fund_action/blob/master/app/services/anybody_authorization_handler.rb[FundAction]
+- https://github.com/CodiTramuntana/decidim-verifications-csv_emails[CSV emails]
+- https://github.com/mainio/decidim-module-access_requests[Access Requests]
+

data/docs/modules/customize/pages/code.adoc

@@ -2,7 +2,7 @@
 
 Decidim is multiple things:
 
-* A command line utility, which can create an application
+* A command-line utility, which can create an application
 * A set of libraries, that the application can use
 
 Most of the time, you should work with the generated application. That application (development_app on this docs) should be named as your project, for instance for Barcelona City Council is `DecidimBarcelona`, so for creating it should be:
@@ -17,7 +17,7 @@ If you want to override/change anything, you can just do it with the same name o
 * https://github.com/gencat/participa/blob/master/app/decorators/decidim/admin/selective_newsletter_form_decorator.rb[Decidim::Admin::SelectiveNewsletterForm]. As it's a decorator you also need to make it available in the https://github.com/gencat/participa/blob/3416992ae095f6ab1e826fee961253514c4ff0ef/config/application.rb#L48[application config]
 * https://github.com/barcelonaregional/decidim-premet25/blob/master/config/initializers/etiquette_validator.rb[EtiquetteValidator.class_eval]
 
-If you want to extend Decidim, the prefered way should be by having a Module. This is a Ruby on Rails Engine which provides ruby code (models, views, controllers, assets, etc). You can use it through multiple ways:
+If you want to extend Decidim, the preferred way should be by having a Module. This is a Ruby on Rails Engine which provides ruby code (models, views, controllers, assets, etc). You can use it in multiple ways:
 
 * Putting it on the same directory as your app and pointing on the Gemfile. https://github.com/AjuntamentdeBarcelona/decidim-barcelona/tree/c210b5338d7ba1338c9879627e081da1441f1946[See example on GitHub]. For instance:
 
@@ -34,3 +34,5 @@ gem "decidim-consultations", git: "https://github.com/decidim/decidim-module-con
 ----
 
 * Publishing it on rubygems.org
+
+You can learn more about xref:develop:modules.adoc[Modules] in the development guide.

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

@@ -69,11 +69,44 @@ Decidim.register_component(:my_component) do |component|
 
   # Import definitions allow data to be imported into a component.
   #
-  # For now supported formats for imports are CSV, JSON and Excel (.xls).
-  # Every resource type needs it's own creator, which creates resource
-  # from parsed data.
+  # For now supported formats for imports are CSV, JSON and Excel (.xlsx).
+  # Every resource type needs it's own creator, which creates resource from
+  # parsed data. You also need to define specific messages for the importer and
+  # can provide some extra options, too.
   component.imports :component_resources do |imports|
+    # Define a form partial if you want to add custom fields to the form
+    # imports.form_view = "decidim/my_component/admin/imports/component_resources_fields"
+    # Define a custom form class name if you want to customize the form object
+    # imports.form_class_name = "MyComponent::Admin::CustomImportForm"
+
+    # Define UI messages for the import functionality
+    imports.messages do |msg|
+      # The resource name is used in the success message:
+      # "X your resources successfully imported" (the "your resources" part)
+      msg.set(:resource_name) { |count: 1| I18n.t("decidim.my_component.admin.imports.resources.component_resources", count: count) }
+      # The title is the message shown at the top of the import page
+      msg.set(:title) { I18n.t("decidim.my_component.admin.imports.title.component_resources") }
+      # The label is what is shown in the import dropdown menu
+      msg.set(:label) { I18n.t("decidim.my_component.admin.imports.label.component_resources") }
+      # The optional help message can be used to provide additional contextual
+      # help for the import file, e.g. how it should be formatted
+      # msg.set(:help) { I18n.t("decidim.my_component.admin.imports.help.component_resources") }
+    end
+
+    # Define the creator that is used to create resources from the import data
     imports.creator MyComponent::ResourceCreator
+
+    # Define an example data set to guide the user how to format the import
+    # file. This will be available for download in the import view for each
+    # supported import format.
+    imports.example do |import_component|
+      organization = import_component.organization
+      [
+        organization.available_locales.map { |l| "title/#{l}" } + organization.available_locales.map { |l| "body/#{l}" },
+        organization.available_locales.map { "Example title" } + organization.available_locales.map { "Example body" },
+        organization.available_locales.map { "Example title 2" } + organization.available_locales.map { "Example body 2" },
+      ]
+    end
   end
 end
 ----

data/docs/modules/develop/pages/{guide_development_with_custom_seed_data.adoc → custom_seed_data.adoc}

@@ -1,4 +1,4 @@
-= Development with custom seed data
+= Custom seed data
 
 The seed data is not only useful for local development, but also for staging environments to showcase your work to your clients. In this case, you might need to customize some of that seed data to make sure it fits your needs.
 

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

@@ -1,13 +1,10 @@
 = Developing Decidim
 
-* xref:develop:guide_architecture.adoc[Architecture]
-* xref:develop:guide_changelog.adoc[Changelog]
-* xref:develop:guide_commands.adoc[Commands]
-* xref:develop:guide_development_app.adoc[Development App]
-* xref:develop:guide_example_apps.adoc[Example Applications]
-* xref:develop:guide_git_conventions.adoc[Git conventions]
-* xref:develop:guide_github_projects.adoc[GitHub Projects Workflow]
-* xref:develop:guide_semver.adoc[Semantic Versioning]
+* xref:develop:guide_example_apps.adoc[1. Example Applications]
+* xref:develop:guide_development_app.adoc[2. Development App]
+* xref:develop:guide_commands.adoc[3. Commands]
+* xref:develop:guide_conventions.adoc[4. Conventions]
+* xref:develop:guide_architecture.adoc[5. Architecture]
 
 == Good to know
 

data/docs/modules/develop/pages/{guide_git_conventions.adoc → guide_conventions.adoc}

@@ -1,4 +1,4 @@
-= Git Conventions
+= Conventions
 
 == GitFlow Branching model
 
@@ -61,6 +61,14 @@ We would like to have all branches following this namings:
 | We only offer support for the last mayor version.
 |===
 
+After the prefix we recommend to add some words that describe what the change is doing, like a summary of the Pull Request title. For instance, some good branch names are:
+
+. refactor/autocomplete
+. feature/add-pagination-to-moderated-users
+. fix/free-text-choice-answer
+
+The rationale behind this is that we don't like to have the issue number (`fix/9123` or just `9123`) as that difficults working with `git`. 
+
 == Git commit messages and Pull Request titles
 
 We recommend following https://chris.beams.io/posts/git-commit/[this guide] for making good git commit messages. It also applies to Pull Request titles. The summary is:
@@ -73,3 +81,19 @@ We recommend following https://chris.beams.io/posts/git-commit/[this guide] for
 . Wrap the body at 72 characters
 . Use the body to explain what and why vs. how
 
+== Changelog
+
+For keeping track of changes we like the rules of https://keepachangelog.com/en/1.0.0/[Keep A Changelog].
+
+In the past we kept a file for all the development of a given version but that was difficult to maintain, as we had conflicts all the time. See the full discussion in https://github.com/decidim/decidim/issues/5908[#5908]. We decided that:
+
+* We will not ask CHANGELOG for all the changes make on this repository. We will ask for CHANGELOG instructions only for special changes that really need some actions on part of developers/implementers or something to comunicate on the releases notes
+* The CHANGELOG will be manually made as part of the release process with the tooling from git (`git log v0.20.0..v0.20.1 --grep " (#[0-9]\+)" --oneline`) or https://github.com/decidim/decidim/compare/v0.20.0...v0.20.1[github]
+
+== Semantic Versioning
+
+For releases we follow https://semver.org/[Semantic Versioning recommendations]. Some details in our case:
+
+* Until v1 there could be changes in the API. We'll let you know on the Release Notes for a given version
+* Upgrading on patch versions should be safe (for instance from 0.20.0 to 0.20.1). The only things that we add are bug fixes and new languages.
+

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

@@ -1,39 +1,72 @@
 = Development App
 
-In order to start developing you will need what is called a `development_app`. This is nearly the same as a new Decidim app (that you can create with `decidim app_name`) but with a Gemfile pre-configured for local development and some other small config modifications.
-You need it in order to have a Rails application configured to lookup Decidim modules from your filesystem. This way changes in your modules will be directly observed by this `development_app`.
+In order to start developing you will need what is called a `development_app`. This is nearly the same as a new Decidim
+app (that you can create with `decidim app_name`) but with a Gemfile pre-configured for local development and some other small config modifications.
 
-You can create a `development_app` from inside the project's root folder with the command:
+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,
+
+1. Configure postgresql with a super-user. For instance, for a user called `decidim_development_app_user` with password `changeme`, it'd be:
+
+[source,console]
+----
+sudo -u postgres psql -c "CREATE USER decidim_development_app_user WITH SUPERUSER CREATEDB NOCREATEROLE PASSWORD 'changeme'"
+----
+
+2. Save the database configuration in your environment variables configuration. If you've 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]
+----
+echo "DATABASE_USERNAME=decidim_development_app_user" >> ~/.rbenv-vars
+echo "DATABASE_PASSWORD=changeme" >> ~/.rbenv-vars
+----
+
+Of course you should change the password before anything.
+
+2. Then you can create a `development_app` from inside the project's root folder with the command:
 
 [source,console]
 ----
 git clone https://github.com/decidim/decidim.git
 cd decidim
 bundle install
-bundle exec rake development_app
-cd development_app
+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.
 
-On creation, this steps are automatically invoked by the generator:
+[NOTE]
+====
+On creation, these steps are automatically invoked by the generator:
 
 * create a `config/database.yml`
 * `bundle install`
 * `bin/rails decidim:upgrade`
-* `bin/rails db:migrate db:seed`
+* `bin/rails db:create`
+* `bin/rails db:migrate`
+* `bin/rails db:seed`
+
+Mind that if everything went well you shouldn't 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 this steps 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. 
 
-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.
+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.
 
 Once the app is created you are ready to start the server:
 
-* `bin/rails s`
+* `bin/rails server`
 
 == Migrations
 
-When creating new migrations in Decidim's modules, you will need to "apply" this migrations to your development_app. The way to do this is by copying the migration from your module into the db/migrate dir of your development_app. Luckily we already have a script that automates this: it copies all missing migrations in development_app/db/migrate. The command is:
+When creating new migrations in Decidim's modules, you will need to "apply" this migrations to your development_app. The way
+to do this is by copying the migration from your module into the db/migrate dir of your development_app. Luckily we already
+have a script that automates this: it copies all missing migrations in development_app/db/migrate. The command is:
 
 [source,console]
 ----
@@ -42,3 +75,25 @@ bin/rails decidim:upgrade
 
 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
+to follow these instructions:
+
+[source,console]
+----
+git pull origin develop
+bin/rails decidim:upgrade
+bin/rails db:migrate
+----
+
+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.
+
+[source,console]
+----
+bin/rake development_app
+----

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

@@ -2,14 +2,14 @@
 
 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.
+NOTE: 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
+* https://github.com/rails/webpacker#usage[Webpacker README]
+* https://edgeguides.rubyonrails.org/webpacker.html[Rails Webpacker guide]
 
 == Requirements
 
@@ -17,12 +17,15 @@ Before starting the migration, please check you have the following dependencies
 
 - 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)
+- Decidim updated to at least v0.25.0.rc4
 
-== Add Webpacker to the application
+== Guide
 
-Follow the steps described https://github.com/rails/webpacker#installation[here]
+=== Add Webpacker to the application
 
-- Install it
+Follow these steps. If you want more information you can find it at the https://github.com/rails/webpacker#installation[Webpacker installation guide].
+
+* Install it
 
 [source,console]
 ----
@@ -40,7 +43,7 @@ This task do a few steps to allow the Rails instance to have a webpacker instanc
 
 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
+=== Copy Decidim custom CSS and Javascript
 
 `webpacker:install` task should have created to you the following dirs structure:
 
@@ -61,11 +64,27 @@ If it's not the case you must create it. Then, copy Decidim customizable assets
 
 These files are hooked into Decidim packs (specifically into decidim-core pack) and will be automatically included inside that pack when compiled.
 
-== Migrate images
+You can download these files directly with these commands:
+
+[source,console]
+----
+mkdir -p app/packs/src/decidim app/packs/stylesheets/decidim app/packs/stylesheets/images
+touch app/packs/src/decidim/.keep app/packs/stylesheets/decidim/.keep app/packs/stylesheets/images/.keep
+wget https://raw.githubusercontent.com/decidim/decidim/develop/decidim-generators/lib/decidim/generators/app_templates/decidim_application.js -O app/packs/src/decidim/decidim_application.js
+wget https://raw.githubusercontent.com/decidim/decidim/develop/decidim-generators/lib/decidim/generators/app_templates/decidim_application.scss -O app/packs/stylesheets/decidim/decidim_application.scss
+wget https://raw.githubusercontent.com/decidim/decidim/develop/decidim-generators/lib/decidim/generators/app_templates/_decidim-settings.scss -O app/packs/stylesheets/decidim/_decidim-settings.scss
+----
+
+=== 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
+[source,console]
+----
+cp -rp app/assets/images/* app/packs/images/
+----
+
+=== 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.
 
@@ -73,26 +92,26 @@ If that CSS file is replacing a Decidim file, there's no need to add it to `deci
 
 If any of the CSS is re-defining CSS vars add them to `_decidim-settings.scss`.
 
-== Migrate javascripts
+=== 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
+=== Update Rails helpers
 
-`javascript_include_tag` and `stylesheet_link_tag` have been replaced by `javascript_pack_tag` and `stylesheet_pack_tag`.
+`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.
 
-For images, if they are in `app/packs/images` you could use `image_pack_tag`.
+For images, if they are in `app/packs/images` you need to replace `ìmage_tag` with `image_pack_tag`.
 
-== Migrate vendorized files and gems
+=== 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
+=== 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:
 
@@ -117,7 +136,7 @@ Decidim::Webpacker.register_stylesheet_import("stylesheets/your_app_extensions")
 Decidim::Webpacker.register_stylesheet_import("stylesheets/your_app_admin_extensions", group: :admin)
 ----
 
-== Remove Sprockets references
+=== Remove Sprockets references
 
 The completely remove Sprockets references from your application:
 
@@ -144,7 +163,17 @@ require "decidim/rails"
 
 * In `config/environments/*.rb` remove any line containing `config.assets.*` (i.e `config.assets.debug = true`)
 
-== Deployment
+=== Help Decidim to know the application's assets folder
+
+To prevent Zeitwerk issues trying to autoload the non-ruby application folders, modify the `config/initializers/decidim.rb` file to include the following:
+
+[source,ruby]
+---
+# Inform Decidim about the assets folder
+Decidim.register_assets_path File.expand_path("app/packs", Rails.application.root)
+---
+
+=== Deployment
 
 The deployment needs to be updated to manually run `npm install` before assets are precompiled.
 
@@ -173,3 +202,16 @@ Also, in the case of Capistrano it's interesting to add to the shared_paths the
 * `tmp/webpacker-cache`
 * `node_modules`
 * `public/decidim-packs`
+
+== Troubleshooting
+
+If you have the following exception when executing `bundle exec rails decidim:upgrade` or `bundle exec rails decidim:webpacker:install`
+
+[source,console]
+----
+npm ERR! code ERESOLVE
+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.

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

@@ -119,3 +119,14 @@ Decidim::Webpacker.register_stylesheet_import("stylesheets/decidim/your_componen
 # Register the admin panel's stylesheet include statement:
 Decidim::Webpacker.register_stylesheet_import("stylesheets/decidim/your_component/your_component_admin", group: :admin)
 ----
+
+=== Help Decidim to know the module's assets folder
+
+To prevent Zeitwerk issues trying to autoload the non-ruby module folders, modify the `lib/[module_name]/engine.rb` file to include the following:
+
+[source,ruby]
+---
+initializer "[module_name].webpacker.assets_path" do
+  Decidim.register_assets_path File.expand_path("app/packs", root)
+end
+---

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

@@ -1,6 +1,6 @@
 = Using machine translations
 
-For multilingual organizations, Decidim includes a way to integrate with amachine translation service. The aim of this integration is to provide machine translations for any user-generated content.
+For multilingual organizations, Decidim includes a way to integrate with a machine translation service. The aim of this integration is to provide machine translations for any user-generated content.
 
 == Flow description
 
@@ -16,6 +16,8 @@ This workflow will only start if the machine translation service is configured i
 == Create your own machine translation service
 
 You can use the `Decidim::Dev::DummyTranslator` service as a base. Any new translator service will need to implement the same API as this class.
+In order to test the `Decidim::Dev::DummyTranslator` you will need to add at the top of `config/initializers/decidim.rb` the following line:
+`require "decidim/dev/dummy_translator"`
 
 == Integrating with async services
 
@@ -33,10 +35,14 @@ This is an option in the Decidim initializer:
 ----
 config.enable_machine_translations = true
 config.machine_translation_service = "MyApp::MyOwnTranslationService"
+config.machine_translation_delay = 0.seconds
 ----
 
 The class will need to be implemented, or reuse one from the community. Check the docs on how to implement a machine translation service.
 
 == Enabling the integration, organization-wise
 
-Each organization will be able to enable/disable machine translations if they want to. They can do that from the organization configuration.
+Each organization will be able to enable / disable the machine translations if they want to. The administrators of the organization perform the action from `Settings` -> `Configuration` admin menu, where they can enable or disable the machine translation system, and also they can select the priority.
+
+* Original text first means that the platform will always display the original content as it has been added by contributors
+* Translated text first means that the platform will always display the translation first.

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

@@ -1,11 +1,114 @@
 = Modules
 
-Modules are subapplications that are run as application plugins.
-They're used to define pieces of functionality that are pluggable to Decidim.
-
-Decidim's modules are no more than Ruby on Rails engines that should be required in the application's `Gemfile`.
-
-You can see some of our more popular modules at https://decidim.org/modules[Decidim's Modules].
+Decidim provides plenty of features, but sometimes you will want to customize or change the default behavior of some
+of them. Usually, there are two ways to do that:
+
+. Creating overrides in your application
+. Creating a new module
+
+The first option is ideal to start hacking with your Decidim implementation but, if you want to create something that others
+can benefit, the best is to create a module in a gem of its own that can be installed anywhere.
+
+NOTE: There's also a third possibility and create a module that is in a sub-folder of the application itself. This approach
+simplifies a little the integration with your app and facilitates a future extraction to a proper external gem. You can
+see some examples of this in the https://github.com/AjuntamentdeBarcelona/decidim-barcelona/tree/master/decidim-census_sms?rgh-link-date=2021-07-23T09%3A19%3A08Z[Ajuntament of Barcelona]
+in the folders `decidim-census_sms`, `decidim-dataviz`, `decidim-ephemeral_participation`, or `decidim-stats`.
+However, we don't recommend this unless you are more in a testing phase and not sure if your work is going to be released
+more generically (most of the times this is the first approach for isolating the features). See more details about the sub-folder approach
+at xref:customize:code.adoc[Code customization].
+
+By creating a new module, you can override almost anything or provide new functionalities.
+The best way to proceed is to first decide what you need, then take a look at how similar things have been done previously in:
+
+- Other external modules
+- Other Decidim instances, and from there extract the feature to a module
+- Decidim source code itself: take into account that Decidim is a bunch of separated modules, so there's much to be learned by looking at the code).
+- Other Rails applications or documentation, because yes, this is Ruby on Rails in the end.
+
+Regarding the type of features you want to develop, these are some typical cases:
+
+- Create a new component or a new participatory space: For this task, Decidim is well prepared already, and when creating a new module by default (running decidim --component my-new-module), it creates a scaffolding for it.
+- Add new routes without many relations to existing features. Then just follow standard guides for creating engines for Ruby on Rails.
+- Creating a verification handler: very typical scenario. Some verification methods are worth extracting to a module as can be very standard.
+- Add content blocks. Content blocks are used currently in the homepage and processes groups, they can transform the user experience quite a lot!
+- xref:customize:views.adoc[Override existing view]: This is quite common but more delicate, it consists of creating the same app/view/some-decidim-view-file file in your module to replace the original one. It's easy but you need to define a strategy for updating your overridden file every time the original in Decidim source code is changed. Some people use the gem Deface for that too.
+- xref:customize:code.adoc[Override other classes or modules in Decidim]: Similar as before, but instead of just overriding files you usually take advantage of the technique of "monkey patching", something that the Ruby language is especially well suited for. Again, you need to be careful between Decidim upgrades if the original files change.
+
+Note also that the two last ones might have conflicts with other modules, so it is worth having a nice suite of tests, both in modules and specific Decidim implementations.
+
+There's a https://decidim.org/modules/[list of modules] that it is updated from time to time, but if you are looking for technology implementations, take a look at these (please contribute to this list if you are implementing something new!):
+
+. Payment gateways: https://github.com/decidiamo/decidim-module-donations[decidiamo/decidim-module-donations]
+. Generic verification handlers:
+.. https://github.com/mainio/decidim-module-access_requests[mainio/decidim-module-access_requests]
+.. https://github.com/Platoniq/decidim-verifications-direct_verifications[Platoniq/decidim-verifications-direct_verifications]
+.. https://github.com/CodiTramuntana/decidim-verifications-custom_csv_census[CodiTramuntana/decidim-verifications-custom_csv_census]
+.. https://github.com/belighted/decidim-module-verifications_omniauth[belighted/decidim-module-verifications_omniauth]
+. New components:
+.. https://github.com/Platoniq/decidim-module-time_tracker[Platoniq/decidim-module-time_tracker]
+.. https://github.com/alabs/decidim-module-calendar[alabs/decidim-module-calendar]
+.. https://github.com/AjuntamentdeBarcelona/decidim-barcelona/tree/master/decidim-dataviz[AjuntamentdeBarcelona/decidim-barcelona]
+. New participatory spaces: None yet! be the first!
+. Using ActionCable (WebSockets): https://github.com/Platoniq/decidim-module-notify[Platoniq/decidim-module-notify]
+. Overriding some core Rails features (i18n locale processing) and make use of advanced strategies like cache: https://github.com/mainio/decidim-module-term_customizer[mainio/decidim-module-term_customizer]
+. Simple hacks to add/improve generic functionalities:
+.. https://github.com/PopulateTools/decidim-module-anonymous_proposals[PopulateTools/decidim-module-anonymous_proposals]
+.. https://github.com/PopulateTools/decidim-module-extra_user_fields[PopulateTools/decidim-module-extra_user_fields]
+.. https://github.com/OpenSourcePolitics/decidim-module-question_captcha[OpenSourcePolitics/decidim-module-question_captcha]
+. Content blocks:
+.. https://github.com/Platoniq/decidim-module-navigation_maps[Platoniq/decidim-module-navigation_maps]
+.. https://github.com/Platoniq/decidim-module-alternative_landing[Platoniq/decidim-module-alternative_landing]
+.. https://github.com/mainio/decidim-module-process_groups_content_block[mainio/decidim-module-process_groups_content_block]
+. New admin zones:
+.. https://github.com/Platoniq/decidim-module-comparative_stats[Platoniq/decidim-module-comparative_stats]
+.. https://github.com/digidemlab/decidim-module-analytics[digidemlab/decidim-module-analytics]
+. Technical hacks (are intended to be used by a developer while customizing a Decidim instance):
+.. https://github.com/mainio/decidim-module-tags[mainio/decidim-module-tags]
+.. https://github.com/mainio/decidim-module-feedback[mainio/decidim-module-feedback]
+. Wild hacks (the implement a variety of techniques to change Decidim existing features):
+.. https://github.com/mainio/decidim-module-simple_proposal[mainio/decidim-module-simple_proposal]
+.. https://github.com/coopdevs/decidim-module-action_delegator[coopdevs/decidim-module-action_delegator]
+.. https://github.com/Platoniq/decidim-module-decidim_awesome[Platoniq/decidim-module-decidim_awesome]
+
+In the case of dealing with more advanced overrides, we recommend implementing some tests that take into account the original files from which the override was created and run it every time a Decidim version is upgraded. Take this https://github.com/coopdevs/decidim-module-action_delegator/blob/master/spec/lib/overrides_spec.rb[checksum checker] as an example.
+
+== Recommendations
+
+First and foremost, don't be afraid to try and start hacking. Once you feel confident enough, read the recommendations
+and best practices below. Remember also that this is free software, so you can do whatever you want in the end.
+These are some opinions on how to improve the quality of the software, but they are not hard rules.
+
+* To be programmed in English (variables, method and class names, comments, etc)
+* To have tests and continuous integration with good test coverage
+* To have documentation in English, explaining:
+  . all the available commands (rake tasks and such)
+  . screenshots of the admin and participant UI
+  . steps to install it
+  . feel free to add in the README if you want who's developing/sponsoring it:
+    - The gem has been developed by $Your_Employer
+    - Development of this gem has been sponsored by $Your_Customer
+  . steps to run the tests locally
+  . how do you want to accept contributions
+* To follow our same rules regarding https://github.com/decidim/decidim/blob/develop/.rubocop.yml[code styling]
+* To have a license file that's compatible with Decidim license (GPL Affero 3)
+* To have a valid .gemspec file
+* To follow the Decidim Social Contract
+* To have a description and other metadata (ie tags) on GitHub or another platform, so it's more discoverable
+* Has good i18 support (all the strings that could be translated are in config/locales/en.yml)
+* If you upload it to GitHub, do it with the naming *decidim-module-<engine_name>*, so it's easier to find on
+the https://github.com/decidim/decidim/network/dependents[dependency graph]. See discussion at https://github.com/decidim/decidim/issues/2396[GitHub].
+* To use Decidim features and APIs when relevant:
+  . Using the Admin panel
+  . Generate logs on Admin panel if admins can operate on it
+  . GraphQL API
+  . Data Portability
+  . Endorsable
+  . Followable
+  . Embeddable
+  . Notifications
+  . If it's a new space, then it should be compatible with the "Context help"
+* Upload the Gem to Rubygems.org so it's easier to deploy to other apps
+* To https://decidim.org/contact/[contact us] so we can publish it at https://decidim.org/modules/[Modules page]
 
 == Types