decidim 0.25.0 → 0.26.0

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of decidim might be problematic. Click here for more details.

Files changed (30) hide show
  1. checksums.yaml +4 -4
  2. data/Rakefile +1 -0
  3. data/docs/antora.yml +1 -1
  4. data/docs/modules/customize/pages/authorizations.adoc +26 -0
  5. data/docs/modules/customize/pages/code.adoc +4 -2
  6. data/docs/modules/develop/pages/components.adoc +36 -3
  7. data/docs/modules/develop/pages/{guide_development_with_custom_seed_data.adoc → custom_seed_data.adoc} +1 -1
  8. data/docs/modules/develop/pages/guide.adoc +5 -8
  9. data/docs/modules/develop/pages/{guide_git_conventions.adoc → guide_conventions.adoc} +25 -1
  10. data/docs/modules/develop/pages/guide_development_app.adoc +66 -11
  11. data/docs/modules/develop/pages/guide_migrate_webpacker_app.adoc +59 -17
  12. data/docs/modules/develop/pages/guide_migrate_webpacker_module.adoc +11 -0
  13. data/docs/modules/develop/pages/machine_translations.adoc +8 -2
  14. data/docs/modules/develop/pages/modules.adoc +109 -6
  15. data/docs/modules/develop/pages/security.adoc +2 -10
  16. data/docs/modules/install/pages/manual.adoc +37 -33
  17. data/lib/decidim/version.rb +1 -1
  18. data/lib/tasks/common_passwords_tasks.rake +12 -0
  19. data/package-lock.json +2250 -90
  20. data/package.json +2 -7
  21. data/packages/browserslist-config/package.json +1 -1
  22. data/packages/core/package.json +1 -1
  23. data/packages/dev/package.json +1 -1
  24. data/packages/elections/package.json +5 -5
  25. data/packages/eslint-config/package.json +1 -1
  26. data/packages/stylelint-config/package.json +1 -1
  27. data/packages/webpacker/package.json +1 -1
  28. metadata +49 -50
  29. data/docs/modules/develop/pages/guide_changelog.adoc +0 -8
  30. data/docs/modules/develop/pages/guide_semver.adoc +0 -7
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: b4b9922e88de129b511673c9ba40958c2afacdcaa07ec038b500af10badf4678
4
- data.tar.gz: c7361bb91075206b25d6f737af846350b949971d6ccb4e4d3a4ada591c2631c0
3
+ metadata.gz: 298209f3c00f41e8f98704545a6c3af1e91a6728d3833a043c94e26d8dba63e3
4
+ data.tar.gz: 8ef259aa25e52150a0a0eb59c84bf0c3e752fd25df034450e6f3f4f4a2fdb471
5
5
  SHA512:
6
- metadata.gz: 806beb8e688782393414029fc83af33b50e9cde93a61f2da505473db0300fe768a560588c8b294149849c79c36a4fc31c38fbba3ff17df701440ae3337ad7cd9
7
- data.tar.gz: 2dd05493e0d2702c7294e391551df7bafe27f4cd5039656591ac609c9b4f78c968f824076542166ce621a001576e590341519628160389abe4c4d6fe1fc13b1d
6
+ metadata.gz: '0968d207a94b288467d4754d8394929ba81a4c8e470a44e1525e9abdf3f7604673d114d85b9112a32ffb9e861606c8e84feddfd0e73b3b35cbeb636c59a36514'
7
+ data.tar.gz: f0aa80e3337e794c1ce0165a4143e5087ce02a9724d9bfc624c90feb8835e097b4ba9147b1b6023833b8ab615b75b8438b3d2dede7f605ec03b4dda2a784885d
data/Rakefile CHANGED
@@ -68,6 +68,7 @@ task :check_locale_completeness do
68
68
  end
69
69
 
70
70
  load "decidim-dev/lib/tasks/generators.rake"
71
+ load "lib/tasks/common_passwords_tasks.rake"
71
72
 
72
73
  desc "Generates a dummy app for testing"
73
74
  task test_app: "decidim:generate_external_test_app"
data/docs/antora.yml CHANGED
@@ -1,5 +1,5 @@
1
1
  name: en
2
- title: "Decidim Developers Documentation"
2
+ title: "Decidim Documentation"
3
3
  version: master
4
4
  asciidoc:
5
5
  attributes:
@@ -20,3 +20,29 @@ Each decidim instance is in full control of its authorizations, and can customiz
20
20
  * 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.
21
21
 
22
22
  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].
23
+
24
+ == Examples
25
+
26
+ Here are some examples:
27
+
28
+ - https://github.com/AjuntamentdeBarcelona/decidim-barcelona/blob/master/app/services/census_authorization_handler.rb[Barcelona (City)]
29
+ - https://github.com/AjuntamentdeCalafell/decidim-calafell/blob/master/app/services/census_authorization_handler.rb[Calafell]
30
+ - https://github.com/diputacioBCN/decidim-diba/blob/master/decidim-diba_census_api/app/services/diba_census_api_authorization_handler.rb[DIBA (Barcelona Province)]
31
+ - https://github.com/AjuntamentDeGava/decidim-gava/blob/master/app/services/census_authorization_handler.rb[Gavà]
32
+ - https://github.com/HospitaletDeLlobregat/decidim-hospitalet/blob/master/app/services/census_authorization_handler.rb[Hospitalet de Llobregat]
33
+ - https://github.com/AjMalgrat/decidim-malgrat/blob/master/app/services/carpetaciutada_handler.rb[Malgrat de Mar]
34
+ - https://github.com/AjuntamentDeMataro/decidimmataro.cat/blob/master/app/services/census_authorization_handler.rb[Mataró]
35
+ - https://github.com/ErabakiPamplona/erabaki/blob/master/app/services/census_authorization_handler.rb[Pamplona]
36
+ - https://github.com/AjuntamentdeReus/decidim/blob/master/app/services/census_authorization_handler.rb[Reus]
37
+ - https://github.com/AjuntamentDeSabadell/decidim-sabadell/blob/master/app/services/census_authorization_handler.rb[Sabadell]
38
+ - https://github.com/AjuntamentdeSantCugat/decidim-sant_cugat/blob/master/app/services/census_authorization_handler.rb[Sant Cugat]
39
+ - https://github.com/AjuntamentDeTerrassa/decidim-terrassa/blob/master/app/services/census_authorization_handler.rb[Terrassa]
40
+ - https://github.com/vilanovailageltru/decidim-vilanova/blob/master/app/services/vilanova_authorization_handler.rb[Vilanova i la Geltrú]
41
+
42
+ Other special verifications:
43
+
44
+ - https://github.com/podemos-info/participa2/tree/master/decidim-module-census_connector[Podemos]
45
+ - https://github.com/ElectricThings/fund_action/blob/master/app/services/anybody_authorization_handler.rb[FundAction]
46
+ - https://github.com/CodiTramuntana/decidim-verifications-csv_emails[CSV emails]
47
+ - https://github.com/mainio/decidim-module-access_requests[Access Requests]
48
+
@@ -2,7 +2,7 @@
2
2
 
3
3
  Decidim is multiple things:
4
4
 
5
- * A command line utility, which can create an application
5
+ * A command-line utility, which can create an application
6
6
  * A set of libraries, that the application can use
7
7
 
8
8
  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
17
17
  * 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]
18
18
  * https://github.com/barcelonaregional/decidim-premet25/blob/master/config/initializers/etiquette_validator.rb[EtiquetteValidator.class_eval]
19
19
 
20
- 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:
20
+ 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:
21
21
 
22
22
  * 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:
23
23
 
@@ -34,3 +34,5 @@ gem "decidim-consultations", git: "https://github.com/decidim/decidim-module-con
34
34
  ----
35
35
 
36
36
  * Publishing it on rubygems.org
37
+
38
+ You can learn more about xref:develop:modules.adoc[Modules] in the development guide.
@@ -69,11 +69,44 @@ Decidim.register_component(:my_component) do |component|
69
69
 
70
70
  # Import definitions allow data to be imported into a component.
71
71
  #
72
- # For now supported formats for imports are CSV, JSON and Excel (.xls).
73
- # Every resource type needs it's own creator, which creates resource
74
- # from parsed data.
72
+ # For now supported formats for imports are CSV, JSON and Excel (.xlsx).
73
+ # Every resource type needs it's own creator, which creates resource from
74
+ # parsed data. You also need to define specific messages for the importer and
75
+ # can provide some extra options, too.
75
76
  component.imports :component_resources do |imports|
77
+ # Define a form partial if you want to add custom fields to the form
78
+ # imports.form_view = "decidim/my_component/admin/imports/component_resources_fields"
79
+ # Define a custom form class name if you want to customize the form object
80
+ # imports.form_class_name = "MyComponent::Admin::CustomImportForm"
81
+
82
+ # Define UI messages for the import functionality
83
+ imports.messages do |msg|
84
+ # The resource name is used in the success message:
85
+ # "X your resources successfully imported" (the "your resources" part)
86
+ msg.set(:resource_name) { |count: 1| I18n.t("decidim.my_component.admin.imports.resources.component_resources", count: count) }
87
+ # The title is the message shown at the top of the import page
88
+ msg.set(:title) { I18n.t("decidim.my_component.admin.imports.title.component_resources") }
89
+ # The label is what is shown in the import dropdown menu
90
+ msg.set(:label) { I18n.t("decidim.my_component.admin.imports.label.component_resources") }
91
+ # The optional help message can be used to provide additional contextual
92
+ # help for the import file, e.g. how it should be formatted
93
+ # msg.set(:help) { I18n.t("decidim.my_component.admin.imports.help.component_resources") }
94
+ end
95
+
96
+ # Define the creator that is used to create resources from the import data
76
97
  imports.creator MyComponent::ResourceCreator
98
+
99
+ # Define an example data set to guide the user how to format the import
100
+ # file. This will be available for download in the import view for each
101
+ # supported import format.
102
+ imports.example do |import_component|
103
+ organization = import_component.organization
104
+ [
105
+ organization.available_locales.map { |l| "title/#{l}" } + organization.available_locales.map { |l| "body/#{l}" },
106
+ organization.available_locales.map { "Example title" } + organization.available_locales.map { "Example body" },
107
+ organization.available_locales.map { "Example title 2" } + organization.available_locales.map { "Example body 2" },
108
+ ]
109
+ end
77
110
  end
78
111
  end
79
112
  ----
@@ -1,4 +1,4 @@
1
- = Development with custom seed data
1
+ = Custom seed data
2
2
 
3
3
  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.
4
4
 
@@ -1,13 +1,10 @@
1
1
  = Developing Decidim
2
2
 
3
- * xref:develop:guide_architecture.adoc[Architecture]
4
- * xref:develop:guide_changelog.adoc[Changelog]
5
- * xref:develop:guide_commands.adoc[Commands]
6
- * xref:develop:guide_development_app.adoc[Development App]
7
- * xref:develop:guide_example_apps.adoc[Example Applications]
8
- * xref:develop:guide_git_conventions.adoc[Git conventions]
9
- * xref:develop:guide_github_projects.adoc[GitHub Projects Workflow]
10
- * xref:develop:guide_semver.adoc[Semantic Versioning]
3
+ * xref:develop:guide_example_apps.adoc[1. Example Applications]
4
+ * xref:develop:guide_development_app.adoc[2. Development App]
5
+ * xref:develop:guide_commands.adoc[3. Commands]
6
+ * xref:develop:guide_conventions.adoc[4. Conventions]
7
+ * xref:develop:guide_architecture.adoc[5. Architecture]
11
8
 
12
9
  == Good to know
13
10
 
@@ -1,4 +1,4 @@
1
- = Git Conventions
1
+ = Conventions
2
2
 
3
3
  == GitFlow Branching model
4
4
 
@@ -61,6 +61,14 @@ We would like to have all branches following this namings:
61
61
  | We only offer support for the last mayor version.
62
62
  |===
63
63
 
64
+ 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:
65
+
66
+ . refactor/autocomplete
67
+ . feature/add-pagination-to-moderated-users
68
+ . fix/free-text-choice-answer
69
+
70
+ 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`.
71
+
64
72
  == Git commit messages and Pull Request titles
65
73
 
66
74
  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
73
81
  . Wrap the body at 72 characters
74
82
  . Use the body to explain what and why vs. how
75
83
 
84
+ == Changelog
85
+
86
+ For keeping track of changes we like the rules of https://keepachangelog.com/en/1.0.0/[Keep A Changelog].
87
+
88
+ 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:
89
+
90
+ * 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
91
+ * 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]
92
+
93
+ == Semantic Versioning
94
+
95
+ For releases we follow https://semver.org/[Semantic Versioning recommendations]. Some details in our case:
96
+
97
+ * Until v1 there could be changes in the API. We'll let you know on the Release Notes for a given version
98
+ * 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.
99
+
@@ -1,39 +1,72 @@
1
1
  = Development App
2
2
 
3
- 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.
4
- 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`.
3
+ In order to start developing you will need what is called a `development_app`. This is nearly the same as a new Decidim
4
+ app (that you can create with `decidim app_name`) but with a Gemfile pre-configured for local development and some other small config modifications.
5
5
 
6
- You can create a `development_app` from inside the project's root folder with the command:
6
+ We recommend that you first have a xref:install:manual.adoc[working Decidim app] so that you have fullfilled all the necessary
7
+ system and services requirements, like having a working Ruby installation, PostgreSQL, Node.JS, etc.
8
+
9
+ You'll need to configure the PostgreSQL database before anything. For this,
10
+
11
+ 1. Configure postgresql with a super-user. For instance, for a user called `decidim_development_app_user` with password `changeme`, it'd be:
12
+
13
+ [source,console]
14
+ ----
15
+ sudo -u postgres psql -c "CREATE USER decidim_development_app_user WITH SUPERUSER CREATEDB NOCREATEROLE PASSWORD 'changeme'"
16
+ ----
17
+
18
+ 2. Save the database configuration in your environment variables configuration. If you've followed the xref:install:manual.adoc[Decidim installation manual],
19
+ then you should have a working https://github.com/rbenv/rbenv-vars[rbenv-vars] in your environment:
20
+
21
+ [source,console]
22
+ ----
23
+ echo "DATABASE_USERNAME=decidim_development_app_user" >> ~/.rbenv-vars
24
+ echo "DATABASE_PASSWORD=changeme" >> ~/.rbenv-vars
25
+ ----
26
+
27
+ Of course you should change the password before anything.
28
+
29
+ 2. Then you can create a `development_app` from inside the project's root folder with the command:
7
30
 
8
31
  [source,console]
9
32
  ----
10
33
  git clone https://github.com/decidim/decidim.git
11
34
  cd decidim
12
35
  bundle install
13
- bundle exec rake development_app
14
- cd development_app
36
+ bin/rake development_app
15
37
  ----
16
38
 
17
39
  A development_app/ entry appears in the .gitignore file, so you don't have to worry about committing the development app by mistake.
18
40
 
19
- On creation, this steps are automatically invoked by the generator:
41
+ [NOTE]
42
+ ====
43
+ On creation, these steps are automatically invoked by the generator:
20
44
 
21
45
  * create a `config/database.yml`
22
46
  * `bundle install`
23
47
  * `bin/rails decidim:upgrade`
24
- * `bin/rails db:migrate db:seed`
48
+ * `bin/rails db:create`
49
+ * `bin/rails db:migrate`
50
+ * `bin/rails db:seed`
51
+
52
+ Mind that if everything went well you shouldn't need to run these commands manually.
53
+ ====
25
54
 
26
- If the default database.yml does not suit your needs you can always configure it at your will and run this steps manually.
55
+ If the default database.yml does not suit your needs you can always configure it at your will and run these steps manually, although
56
+ we recommend that you make the database configurations with environment variables (ENV VARs) so it's easy for you to regenerate the database.
27
57
 
28
- 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.
58
+ The last command will set your database and add some example data (called "seed data") so that you can start trying Decidim.
59
+ We don't recommend using seed data for production environments, but it's useful for local development and staging environments.
29
60
 
30
61
  Once the app is created you are ready to start the server:
31
62
 
32
- * `bin/rails s`
63
+ * `bin/rails server`
33
64
 
34
65
  == Migrations
35
66
 
36
- 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:
67
+ When creating new migrations in Decidim's modules, you will need to "apply" this migrations to your development_app. The way
68
+ to do this is by copying the migration from your module into the db/migrate dir of your development_app. Luckily we already
69
+ have a script that automates this: it copies all missing migrations in development_app/db/migrate. The command is:
37
70
 
38
71
  [source,console]
39
72
  ----
@@ -42,3 +75,25 @@ bin/rails decidim:upgrade
42
75
 
43
76
  Anyway we recommend re-creating your development_app every once in a while.
44
77
 
78
+ == Updating from develop
79
+
80
+ We recommend that you periodically update your codebase with the last changes from the main repository. For this, you'll need
81
+ to follow these instructions:
82
+
83
+ [source,console]
84
+ ----
85
+ git pull origin develop
86
+ bin/rails decidim:upgrade
87
+ bin/rails db:migrate
88
+ ----
89
+
90
+ And restart your rails server (with Ctrl+C to stop it).
91
+
92
+ == Re-creating the development_app
93
+
94
+ If you're working with old branches or there were multiple changes in develop, you'll need to re-create your development_app.
95
+
96
+ [source,console]
97
+ ----
98
+ bin/rake development_app
99
+ ----
@@ -2,14 +2,14 @@
2
2
 
3
3
  In order to migrate an existing Decidim app to Webpacker, there are a few changes your need to run in your code.
4
4
 
5
- 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.
5
+ 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.
6
6
 
7
7
  == About Webpacker
8
8
 
9
9
  It's recommended to understand how Webpacker works. More information:
10
10
 
11
- * https://github.com/rails/webpacker#usage
12
- * https://edgeguides.rubyonrails.org/webpacker.html
11
+ * https://github.com/rails/webpacker#usage[Webpacker README]
12
+ * https://edgeguides.rubyonrails.org/webpacker.html[Rails Webpacker guide]
13
13
 
14
14
  == Requirements
15
15
 
@@ -17,12 +17,15 @@ Before starting the migration, please check you have the following dependencies
17
17
 
18
18
  - Node.js version 16.9.x (this version is mandatory)
19
19
  - Npm version 7.21.x (it works with other versions, but this is the recommended)
20
+ - Decidim updated to at least v0.25.0.rc4
20
21
 
21
- == Add Webpacker to the application
22
+ == Guide
22
23
 
23
- Follow the steps described https://github.com/rails/webpacker#installation[here]
24
+ === Add Webpacker to the application
24
25
 
25
- - Install it
26
+ Follow these steps. If you want more information you can find it at the https://github.com/rails/webpacker#installation[Webpacker installation guide].
27
+
28
+ * Install it
26
29
 
27
30
  [source,console]
28
31
  ----
@@ -40,7 +43,7 @@ This task do a few steps to allow the Rails instance to have a webpacker instanc
40
43
 
41
44
  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.
42
45
 
43
- == Copy Decidim custom CSS and Javascript
46
+ === Copy Decidim custom CSS and Javascript
44
47
 
45
48
  `webpacker:install` task should have created to you the following dirs structure:
46
49
 
@@ -61,11 +64,27 @@ If it's not the case you must create it. Then, copy Decidim customizable assets
61
64
 
62
65
  These files are hooked into Decidim packs (specifically into decidim-core pack) and will be automatically included inside that pack when compiled.
63
66
 
64
- == Migrate images
67
+ You can download these files directly with these commands:
68
+
69
+ [source,console]
70
+ ----
71
+ mkdir -p app/packs/src/decidim app/packs/stylesheets/decidim app/packs/stylesheets/images
72
+ touch app/packs/src/decidim/.keep app/packs/stylesheets/decidim/.keep app/packs/stylesheets/images/.keep
73
+ 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
74
+ 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
75
+ 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
76
+ ----
77
+
78
+ === Migrate images
65
79
 
66
80
  Copy the existing images from `app/assets/images` to `app/packs/images`. Images will be available at `/media/images/image.png`
67
81
 
68
- == Migrate stylesheets
82
+ [source,console]
83
+ ----
84
+ cp -rp app/assets/images/* app/packs/images/
85
+ ----
86
+
87
+ === Migrate stylesheets
69
88
 
70
89
  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.
71
90
 
@@ -73,26 +92,26 @@ If that CSS file is replacing a Decidim file, there's no need to add it to `deci
73
92
 
74
93
  If any of the CSS is re-defining CSS vars add them to `_decidim-settings.scss`.
75
94
 
76
- == Migrate javascripts
95
+ === Migrate javascripts
77
96
 
78
97
  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.
79
98
 
80
99
  If that JS file is replacing a Decidim file, there's no need to add it to `decidim_application.js`
81
100
 
82
- == Update Rails helpers
101
+ === Update Rails helpers
83
102
 
84
- `javascript_include_tag` and `stylesheet_link_tag` have been replaced by `javascript_pack_tag` and `stylesheet_pack_tag`.
103
+ `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.
85
104
 
86
- For images, if they are in `app/packs/images` you could use `image_pack_tag`.
105
+ For images, if they are in `app/packs/images` you need to replace `ìmage_tag` with `image_pack_tag`.
87
106
 
88
- == Migrate vendorized files and gems
107
+ === Migrate vendorized files and gems
89
108
 
90
109
  Sometimes assets are included in `vendor/assets/` folder or imported from gems. For each specific one you should check:
91
110
 
92
111
  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.
93
112
  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.
94
113
 
95
- == Optional asset includes
114
+ === Optional asset includes
96
115
 
97
116
  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:
98
117
 
@@ -117,7 +136,7 @@ Decidim::Webpacker.register_stylesheet_import("stylesheets/your_app_extensions")
117
136
  Decidim::Webpacker.register_stylesheet_import("stylesheets/your_app_admin_extensions", group: :admin)
118
137
  ----
119
138
 
120
- == Remove Sprockets references
139
+ === Remove Sprockets references
121
140
 
122
141
  The completely remove Sprockets references from your application:
123
142
 
@@ -144,7 +163,17 @@ require "decidim/rails"
144
163
 
145
164
  * In `config/environments/*.rb` remove any line containing `config.assets.*` (i.e `config.assets.debug = true`)
146
165
 
147
- == Deployment
166
+ === Help Decidim to know the application's assets folder
167
+
168
+ To prevent Zeitwerk issues trying to autoload the non-ruby application folders, modify the `config/initializers/decidim.rb` file to include the following:
169
+
170
+ [source,ruby]
171
+ ---
172
+ # Inform Decidim about the assets folder
173
+ Decidim.register_assets_path File.expand_path("app/packs", Rails.application.root)
174
+ ---
175
+
176
+ === Deployment
148
177
 
149
178
  The deployment needs to be updated to manually run `npm install` before assets are precompiled.
150
179
 
@@ -173,3 +202,16 @@ Also, in the case of Capistrano it's interesting to add to the shared_paths the
173
202
  * `tmp/webpacker-cache`
174
203
  * `node_modules`
175
204
  * `public/decidim-packs`
205
+
206
+ == Troubleshooting
207
+
208
+ If you have the following exception when executing `bundle exec rails decidim:upgrade` or `bundle exec rails decidim:webpacker:install`
209
+
210
+ [source,console]
211
+ ----
212
+ npm ERR! code ERESOLVE
213
+ npm ERR! ERESOLVE unable to resolve dependency tree
214
+ npm ERR!
215
+ ----
216
+
217
+ Then you need to check again that you're using the correct Node.js and NPM versions.
@@ -119,3 +119,14 @@ Decidim::Webpacker.register_stylesheet_import("stylesheets/decidim/your_componen
119
119
  # Register the admin panel's stylesheet include statement:
120
120
  Decidim::Webpacker.register_stylesheet_import("stylesheets/decidim/your_component/your_component_admin", group: :admin)
121
121
  ----
122
+
123
+ === Help Decidim to know the module's assets folder
124
+
125
+ To prevent Zeitwerk issues trying to autoload the non-ruby module folders, modify the `lib/[module_name]/engine.rb` file to include the following:
126
+
127
+ [source,ruby]
128
+ ---
129
+ initializer "[module_name].webpacker.assets_path" do
130
+ Decidim.register_assets_path File.expand_path("app/packs", root)
131
+ end
132
+ ---
@@ -1,6 +1,6 @@
1
1
  = Using machine translations
2
2
 
3
- 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.
3
+ 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.
4
4
 
5
5
  == Flow description
6
6
 
@@ -16,6 +16,8 @@ This workflow will only start if the machine translation service is configured i
16
16
  == Create your own machine translation service
17
17
 
18
18
  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.
19
+ In order to test the `Decidim::Dev::DummyTranslator` you will need to add at the top of `config/initializers/decidim.rb` the following line:
20
+ `require "decidim/dev/dummy_translator"`
19
21
 
20
22
  == Integrating with async services
21
23
 
@@ -33,10 +35,14 @@ This is an option in the Decidim initializer:
33
35
  ----
34
36
  config.enable_machine_translations = true
35
37
  config.machine_translation_service = "MyApp::MyOwnTranslationService"
38
+ config.machine_translation_delay = 0.seconds
36
39
  ----
37
40
 
38
41
  The class will need to be implemented, or reuse one from the community. Check the docs on how to implement a machine translation service.
39
42
 
40
43
  == Enabling the integration, organization-wise
41
44
 
42
- Each organization will be able to enable/disable machine translations if they want to. They can do that from the organization configuration.
45
+ 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.
46
+
47
+ * Original text first means that the platform will always display the original content as it has been added by contributors
48
+ * Translated text first means that the platform will always display the translation first.
@@ -1,11 +1,114 @@
1
1
  = Modules
2
2
 
3
- Modules are subapplications that are run as application plugins.
4
- They're used to define pieces of functionality that are pluggable to Decidim.
5
-
6
- Decidim's modules are no more than Ruby on Rails engines that should be required in the application's `Gemfile`.
7
-
8
- You can see some of our more popular modules at https://decidim.org/modules[Decidim's Modules].
3
+ Decidim provides plenty of features, but sometimes you will want to customize or change the default behavior of some
4
+ of them. Usually, there are two ways to do that:
5
+
6
+ . Creating overrides in your application
7
+ . Creating a new module
8
+
9
+ The first option is ideal to start hacking with your Decidim implementation but, if you want to create something that others
10
+ can benefit, the best is to create a module in a gem of its own that can be installed anywhere.
11
+
12
+ NOTE: There's also a third possibility and create a module that is in a sub-folder of the application itself. This approach
13
+ simplifies a little the integration with your app and facilitates a future extraction to a proper external gem. You can
14
+ 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]
15
+ in the folders `decidim-census_sms`, `decidim-dataviz`, `decidim-ephemeral_participation`, or `decidim-stats`.
16
+ 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
17
+ more generically (most of the times this is the first approach for isolating the features). See more details about the sub-folder approach
18
+ at xref:customize:code.adoc[Code customization].
19
+
20
+ By creating a new module, you can override almost anything or provide new functionalities.
21
+ 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:
22
+
23
+ - Other external modules
24
+ - Other Decidim instances, and from there extract the feature to a module
25
+ - 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).
26
+ - Other Rails applications or documentation, because yes, this is Ruby on Rails in the end.
27
+
28
+ Regarding the type of features you want to develop, these are some typical cases:
29
+
30
+ - 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.
31
+ - Add new routes without many relations to existing features. Then just follow standard guides for creating engines for Ruby on Rails.
32
+ - Creating a verification handler: very typical scenario. Some verification methods are worth extracting to a module as can be very standard.
33
+ - Add content blocks. Content blocks are used currently in the homepage and processes groups, they can transform the user experience quite a lot!
34
+ - 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.
35
+ - 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.
36
+
37
+ 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.
38
+
39
+ 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!):
40
+
41
+ . Payment gateways: https://github.com/decidiamo/decidim-module-donations[decidiamo/decidim-module-donations]
42
+ . Generic verification handlers:
43
+ .. https://github.com/mainio/decidim-module-access_requests[mainio/decidim-module-access_requests]
44
+ .. https://github.com/Platoniq/decidim-verifications-direct_verifications[Platoniq/decidim-verifications-direct_verifications]
45
+ .. https://github.com/CodiTramuntana/decidim-verifications-custom_csv_census[CodiTramuntana/decidim-verifications-custom_csv_census]
46
+ .. https://github.com/belighted/decidim-module-verifications_omniauth[belighted/decidim-module-verifications_omniauth]
47
+ . New components:
48
+ .. https://github.com/Platoniq/decidim-module-time_tracker[Platoniq/decidim-module-time_tracker]
49
+ .. https://github.com/alabs/decidim-module-calendar[alabs/decidim-module-calendar]
50
+ .. https://github.com/AjuntamentdeBarcelona/decidim-barcelona/tree/master/decidim-dataviz[AjuntamentdeBarcelona/decidim-barcelona]
51
+ . New participatory spaces: None yet! be the first!
52
+ . Using ActionCable (WebSockets): https://github.com/Platoniq/decidim-module-notify[Platoniq/decidim-module-notify]
53
+ . 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]
54
+ . Simple hacks to add/improve generic functionalities:
55
+ .. https://github.com/PopulateTools/decidim-module-anonymous_proposals[PopulateTools/decidim-module-anonymous_proposals]
56
+ .. https://github.com/PopulateTools/decidim-module-extra_user_fields[PopulateTools/decidim-module-extra_user_fields]
57
+ .. https://github.com/OpenSourcePolitics/decidim-module-question_captcha[OpenSourcePolitics/decidim-module-question_captcha]
58
+ . Content blocks:
59
+ .. https://github.com/Platoniq/decidim-module-navigation_maps[Platoniq/decidim-module-navigation_maps]
60
+ .. https://github.com/Platoniq/decidim-module-alternative_landing[Platoniq/decidim-module-alternative_landing]
61
+ .. https://github.com/mainio/decidim-module-process_groups_content_block[mainio/decidim-module-process_groups_content_block]
62
+ . New admin zones:
63
+ .. https://github.com/Platoniq/decidim-module-comparative_stats[Platoniq/decidim-module-comparative_stats]
64
+ .. https://github.com/digidemlab/decidim-module-analytics[digidemlab/decidim-module-analytics]
65
+ . Technical hacks (are intended to be used by a developer while customizing a Decidim instance):
66
+ .. https://github.com/mainio/decidim-module-tags[mainio/decidim-module-tags]
67
+ .. https://github.com/mainio/decidim-module-feedback[mainio/decidim-module-feedback]
68
+ . Wild hacks (the implement a variety of techniques to change Decidim existing features):
69
+ .. https://github.com/mainio/decidim-module-simple_proposal[mainio/decidim-module-simple_proposal]
70
+ .. https://github.com/coopdevs/decidim-module-action_delegator[coopdevs/decidim-module-action_delegator]
71
+ .. https://github.com/Platoniq/decidim-module-decidim_awesome[Platoniq/decidim-module-decidim_awesome]
72
+
73
+ 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.
74
+
75
+ == Recommendations
76
+
77
+ First and foremost, don't be afraid to try and start hacking. Once you feel confident enough, read the recommendations
78
+ and best practices below. Remember also that this is free software, so you can do whatever you want in the end.
79
+ These are some opinions on how to improve the quality of the software, but they are not hard rules.
80
+
81
+ * To be programmed in English (variables, method and class names, comments, etc)
82
+ * To have tests and continuous integration with good test coverage
83
+ * To have documentation in English, explaining:
84
+ . all the available commands (rake tasks and such)
85
+ . screenshots of the admin and participant UI
86
+ . steps to install it
87
+ . feel free to add in the README if you want who's developing/sponsoring it:
88
+ - The gem has been developed by $Your_Employer
89
+ - Development of this gem has been sponsored by $Your_Customer
90
+ . steps to run the tests locally
91
+ . how do you want to accept contributions
92
+ * To follow our same rules regarding https://github.com/decidim/decidim/blob/develop/.rubocop.yml[code styling]
93
+ * To have a license file that's compatible with Decidim license (GPL Affero 3)
94
+ * To have a valid .gemspec file
95
+ * To follow the Decidim Social Contract
96
+ * To have a description and other metadata (ie tags) on GitHub or another platform, so it's more discoverable
97
+ * Has good i18 support (all the strings that could be translated are in config/locales/en.yml)
98
+ * If you upload it to GitHub, do it with the naming *decidim-module-<engine_name>*, so it's easier to find on
99
+ the https://github.com/decidim/decidim/network/dependents[dependency graph]. See discussion at https://github.com/decidim/decidim/issues/2396[GitHub].
100
+ * To use Decidim features and APIs when relevant:
101
+ . Using the Admin panel
102
+ . Generate logs on Admin panel if admins can operate on it
103
+ . GraphQL API
104
+ . Data Portability
105
+ . Endorsable
106
+ . Followable
107
+ . Embeddable
108
+ . Notifications
109
+ . If it's a new space, then it should be compatible with the "Context help"
110
+ * Upload the Gem to Rubygems.org so it's easier to deploy to other apps
111
+ * To https://decidim.org/contact/[contact us] so we can publish it at https://decidim.org/modules/[Modules page]
9
112
 
10
113
  == Types
11
114