decidim 0.23.6 → 0.24.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd64e9c973cde4c71d9f0d39a1fa84972135ae3ddcfa91aedfa3f250d953aa86
-  data.tar.gz: 738b2d35647c9b205ea943c69b73a4ad78d51207a8feb380fb91b6efdf641e78
+  metadata.gz: 9b8cc06811557ba36021b2bcee0d250bc319bf9b64e8f2510c35a3952772ca34
+  data.tar.gz: c43b462d704a1f81d06616e969faa559bb718fc80ff32f75149e35e7dcbce715
 SHA512:
-  metadata.gz: 61f5edf1d9a95dc0528ce38c6f47086148562f714e7d46e122d810cdde640f8a445f62e22a5b6756212fbe79d9d3073e3ddd0abc9c10b256503c4d7301cbaf3e
-  data.tar.gz: 3e379c57d7c5cc9d272bb4863938f105e236c9ef125a46853ac63ba98078730e07f7a8f107c9f40660dcfc610446b08b4ddf6f61c0dba6820c6c23ae51b9e0fb
+  metadata.gz: c8442ad8b7906eed963bdc31cf4787e91bb9836232bd565f4e31e640ec05378116291b44c8580d238cc966a8bf2f5a1ef2f8f3d0cc2368208e412af5eab643b8
+  data.tar.gz: d2b06c1b6980cd9b88ba646c4ec159f7f08cad01887c407d5a23e96c4a378087977b9fe42e85dc224b12679aec4a7496fdbdd02ae5b68f55639620c404106913

data/Rakefile

@@ -83,6 +83,7 @@ desc "Bundle all Gemfiles"
 task :bundle do
   [".", "decidim-generators", "decidim_app-design"].each do |dir|
     Bundler.with_original_env do
+      puts "Updating #{dir}...\n"
       Dir.chdir(dir) { sh "bundle install" }
     end
   end

data/docs/README.adoc

@@ -0,0 +1,74 @@
+= Decidim Developer Documentation
+
+== What's this?
+
+This is the internal Decidim documentation.
+If you want to see it in a nice UI you can do it at the https://docs.decidim.org[Decidim Documentation Site].
+Some of the sections are available on https://github.com/decidim/documentation[Decidim Documentation repository].
+
+== How this works?
+
+This is made with https://antora.org/[Antora].
+It uses https://asciidoc.org/[AsciiDoc] mark-up document format.
+It's pretty similar to Markdown, although is more standarized and can do more complex things.
+Read more about https://asciidoctor.org/docs/asciidoc-vs-markdown/[Markdown vs AsciiDoc].
+
+If you want to convert from Markdown to AsciiDoc:
+
+. online pandoc conversor or
+. using kramdoc:
+
+[source,bash]
+----
+gem install kramdown-asciidoc
+kramdoc --format=GFM --output=your-doc.adoc --wrap=ventilate your-doc.md
+----
+
+The nice thing about Antora is that you can have multi-repositories for your documentation, so we have some technical sections in this repository (like Install, Customize and Develop) and other sections that are not for developers or system administrators on the https://github.com/decidim/documentation[other repository].
+
+== Local development
+
+If you want to try changes in this folder and how it'd be shown in https://docs.decidim.org[Decidim Documentation site], you need to do these next steps:
+
+. Clone the repository
+. Install dependencies
+. Change the antora-playbook.yml url key in source
+. Build the antora playbook
+. Open the generated website with your web browser
+
+In detail each one of these steps are:
+
+[source,bash]
+----
+# 1. Clone the repository
+git clone https://github.com/decidim/documentation
+# 2. Install dependencies
+npm install
+# 3. Change the antora-playbook.yml url key in source
+# 4. Build the antora playbook
+npm run build
+# 5. Open the generated website with your web browser
+xdg-open build/site/index.html
+----
+
+Regarding "3. Change the antora-playbook.yml url key in source", if this is the configuration at antora-playbook.yml:
+
+[source,yaml]
+----
+   - url: https://github.com/decidim/decidim
+     start_path: docs
+     branches: develop
+----
+
+Then the result would be:
+
+[source,yaml]
+----
+   - url: /home/youruser/Work/decidim/decidim
+     start_path: docs
+     branches: develop
+----
+
+== Add a new link in the sidebar
+
+For adding a new link in the sidebar you need to add it in https://raw.githubusercontent.com/decidim/documentation/master/en/modules/ROOT/nav.adoc[nav.adoc file]

data/docs/antora.yml

@@ -0,0 +1,7 @@
+name: en
+title: "Decidim Developers Documentation"
+version: master
+asciidoc:
+  attributes:
+    page-lang: en@
+

data/docs/modules/configure/pages/environment_variables.adoc

@@ -0,0 +1,69 @@
+= Environment Variables
+
+We try to let most of the things defined through Environment Variables, as https://12factor.net/config[12factor applications's config]. You'll need to configure through your hosting provider (for example in Heroku), through a gem like `figaro` or through docker-compose `env_file`.
+
+.Decidim Env Vars
+|===
+|Name |Value
+
+|DATABASE_HOST
+|Hostname for the Postgres database. Default is `localhost`.
+
+|DATABASE_PASSWORD
+|Password for the Postgres database
+
+|DATABASE_PORT
+|Port for the Postgres database. Default is `5432`.
+
+|DATABASE_USERNAME
+|Username for the Postgres database
+
+|GEOCODER_API_KEY
+|API key for Geocoder HERE.com
+
+|OMNIAUTH_FACEBOOK_APP_ID
+|App ID for enabling access through Facebook.com accounts. See xref:services:social_providers.adoc[Social Providers].
+
+|OMNIAUTH_FACEBOOK_APP_SECRET
+|App Secret for enabling access through Facebook.com accounts. See xref:services:social_providers.adoc[Social Providers].
+
+|OMNIAUTH_GOOGLE_CLIENT_ID
+|Client ID for enabling access through Google.com accounts. See xref:services:social_providers.adoc[Social Providers].
+
+|OMNIAUTH_GOOGLE_CLIENT_SECRET
+|Client Secret for enabling access through Google.com accounts. See xref:services:social_providers.adoc[Social Providers].
+
+|OMNIAUTH_TWITTER_API_KEY
+|API Key for enabling access through Google.com accounts. See xref:services:social_providers.adoc[Social Providers].
+
+|OMNIAUTH_TWITTER_API_SECRET
+|API Secret for enabling access through Google.com accounts. See xref:services:social_providers.adoc[Social Providers].
+
+|PORT
+|Specifies the `port` that Puma will listen on to receive requests. Default is 3000.
+
+|RAILS_ENV
+|Environment for Ruby on Rails. If it's on your local machine for development, then it should be `development`. If it's on server it should be `production`. Please take care that this has security implications. You DON'T want to be running a production application on development mode.
+
+|RAILS_LOG_TO_STDOUT
+|If true it'll show the log contents on the shell Standard Out. It's special relevant on certain hosting providers (for example, Heroku or Docker). It's also part of https://12factor.net/logs[12factor's recomendations].
+
+|SECRET_KEY_BASE
+|Secret key base for the Application. It's specially important that this is kept secret from the outside word; do NOT publish it on GitHub/GitLab/BitBucket.
+
+|SMTP_ADDRESS
+|Hostname for the SMTP server, for sending emails. See xref:services:smtp.adoc[SMTP]
+
+|SMTP_DOMAIN
+|Domain for the SMTP server, for sending emails. See xref:services:smtp.adoc[SMTP]
+
+|SMTP_PASSWORD
+|Password for the SMTP server, for sending emails. See xref:services:smtp.adoc[SMTP]
+
+|SMTP_USERNAME
+|Username for the SMTP server, for sending emails. See xref:services:smtp.adoc[SMTP]
+
+|===
+
+Please take care that all these configurations would be the defaults but *some of these could also be changed on a Multitenant's System configuration* (for instance SMTP or OAUTH providers).
+

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

@@ -0,0 +1,16 @@
+= Configuring
+
+Decidim is a Ruby on Rails library, and as such we try to follow their conventions. Please read https://guides.rubyonrails.org/configuring.html[Configuring Rails Applications].
+
+Just as a reminder, these files are important:
+
+* config/database.yml
+* config/secrets.yml
+
+Although most of these settings you can change them through xref:configure:environment_variables.adoc[Environment Variables].
+
+You also have more settings in:
+
+* xref:configure:initializer.adoc[Decidim initializer file].
+* System panel.
+

data/docs/modules/configure/pages/initializer.adoc

@@ -0,0 +1,376 @@
+= Initializer
+
+There are some settings that you'll need to change in the `config/initializer/decidim.rb` file.
+
+This is where you can change the behaviour defined on the diferent components (most notably from `decidim-core`).
+
+After making changes to this file you'll need to also restart your application server.
+
+== Application name
+
+The name of the application.
+
+[source,ruby]
+....
+  config.application_name = "My Application Name"
+....
+
+== Default mailer sender
+
+The email that will be used as sender in all emails from Decidim.
+
+[source,ruby]
+....
+  config.mailer_sender = "change-me@domain.org"
+....
+
+== Available locales
+
+Sets the list of available locales for the whole application.
+
+When an organization is created through the System area, system admins will
+be able to choose the available languages for that organization. That list
+of languages will be equal or a subset of the list in this file.
+
+[source,ruby]
+....
+  config.available_locales = [:en, :ca, :es]
+....
+
+== Restrict system access
+
+For extra security, restrict access to the system part with an authorized ip list.
+You can use a single ip like ("1.2.3.4"), or an ip subnet like ("1.2.3.4/24")
+You may specify multiple ip in an array ["1.2.3.4", "1.2.3.4/24"]
+
+[source,ruby]
+....
+  config.system_accesslist_ips = ["127.0.0.1"]
+....
+
+== Default locale
+
+Sets the default locale for new organizations. When creating a new
+organization from the System area, system admins will be able to overwrite
+this value for that specific organization.
+
+[source,ruby]
+....
+  config.default_locale = :en
+....
+
+== Content Processors
+
+Defines a list of custom content processors. They are used to parse and
+render specific tags inside some user-provided content. Check the xref:develop:content_processor.adoc[Content Processor]
+docs for more info.
+
+[source,ruby]
+....
+  config.content_processors = []
+....
+
+== Force SSL
+
+Whether SSL should be enabled or not. Recommended for extra security.
+
+[source,ruby]
+....
+  config.force_ssl = true
+....
+
+== Geocoder configuration
+
+Allows to make geographical mapping in some components, like Proposals or Meetings. It must be configured against a OpenStreetMap provider. See xref:services:geocoder.adoc[Geocoder service documentation].
+
+[source,ruby]
+....
+  config.geocoder = {
+    static_map_url: "https://image.maps.ls.hereapi.com/mia/1.6/mapview",
+    here_api_key: Rails.application.secrets.geocoder[:here_api_key]
+  }
+....
+
+== Custom resource reference
+
+Custom resource reference generator method. See the See xref:admin:system_panel.adoc[System panel docs] for more information.
+
+[source,ruby]
+....
+  config.reference_generator = lambda do |resource, component|
+    # Implement your custom method to generate resources references
+    "1234-#{resource.id}"
+  end
+....
+
+== Currency unit
+
+Allows to change the currency unit, for instance to `$`. By default is `€`.
+
+[source,ruby]
+....
+  config.currency_unit = "€"
+....
+
+
+== Image uploader settings
+
+=== Quality
+
+Defines the quality of image uploads after processing. Image uploads are
+processed by Decidim, this value helps reduce the size of the files.
+
+[source,ruby]
+....
+
+  config.image_uploader_quality = 80
+....
+
+=== Attachment file size
+
+The maximum file size of an attachment
+
+Mind that this depends on your environment, for instance you could also need to change your web server configuration (nginx, apache, etc).
+
+[source,ruby]
+....
+  config.maximum_attachment_size = 10.megabytes
+....
+
+=== User avatar file size
+
+  # The maximum file size for a user avatar
+
+Mind that this depends on your environment, for instance you could also need to change your web server configuration (nginx, apache, etc).
+
+[source,ruby]
+....
+  config.maximum_avatar_size = 10.megabytes
+....
+
+== Reports
+
+The number of reports which a resource can receive before hiding it.
+
+[source,ruby]
+....
+  config.max_reports_before_hiding = 3
+....
+
+== Custom HTML Header snippets
+
+The most common use is to integrate third-party services that require some
+extra JavaScript or CSS. Also, you can use it to add extra meta tags to the
+HTML. Note that this will only be rendered in public pages, not in the admin
+section.
+
+Before enabling this you should ensure that any tracking that might be done
+is in accordance with the rules and regulations that apply to your
+environment and usage scenarios. This component also comes with the risk
+that an organization's administrator injects malicious scripts to spy on or
+take over user accounts.
+
+[source,ruby]
+....
+  config.enable_html_header_snippets = false
+....
+
+== Track newsletter links
+
+Allow organizations admins to track newsletter links, trough UTMs. See https://en.wikipedia.org/wiki/UTM_parameters[UTM parameters in Wikipedia].
+
+[source,ruby]
+....
+  config.track_newsletter_links = true
+....
+
+== Data portability expiry time
+
+Amount of time that the data portability files will be available in the server.
+
+[source,ruby]
+....
+  config.data_portability_expiry_time = 7.days
+....
+
+== Throttling settings
+
+Security settings for blocking possible attacks.
+
+=== Max requests
+
+Max requests in a time period to prevent DoS attacks. Only applied on production.
+
+[source,ruby]
+....
+  config.throttling_max_requests = 100
+....
+
+=== Period
+
+Time window in which the throttling is applied.
+
+[source,ruby]
+....
+  config.throttling_period = 1.minute
+....
+
+== Unconfirmed access for users
+
+Time window were users can access the website even if their email is not confirmed.
+
+[source,ruby]
+....
+  config.unconfirmed_access_for = 2.days
+....
+
+== Base path for uploads
+
+A base path for the uploads. If set, make sure it ends in a slash.
+Uploads will be set to `<base_path>/uploads/`. This can be useful if you
+want to use the same uploads place for both staging and production
+environments, but in different folders.
+
+If not set, it will be ignored.
+
+[source,ruby]
+....
+  config.base_uploads_path = nil
+....
+
+== SMS gateway configuration
+
+If you want to verify your users by sending a verification code via
+SMS you need to provide a SMS gateway service class.
+
+An example class would be something like:
+
+[source,ruby]
+....
+class MySMSGatewayService
+  attr_reader :mobile_phone_number, :code
+  def initialize(mobile_phone_number, code)
+    @mobile_phone_number = mobile_phone_number
+    @code = code
+  end
+  def deliver_code
+    # Actual code to deliver the code
+    true
+  end
+end
+....
+
+Then you'll need to configure it in the Decidim initializer:
+
+[source,ruby]
+....
+  config.sms_gateway_service = "MySMSGatewayService"
+....
+
+== Timestamp service configuration
+
+Used by `decidim-initiatives`.
+
+Provide a class to generate a timestamp for a document. The instances of
+this class are initialized with a hash containing the :document key with
+the document to be timestamped as value. The istances respond to a
+timestamp public method with the timestamp.
+
+An example class would be something like:
+
+[source,ruby]
+....
+class MyTimestampService
+  attr_accessor :document
+  def initialize(args = {})
+    @document = args.fetch(:document)
+  end
+  def timestamp
+    # Code to generate timestamp
+    "My timestamp"
+  end
+end
+....
+
+Then you'll need to configure it in the Decidim initializer:
+
+[source,ruby]
+....
+  config.timestamp_service = "MyTimestampService"
+....
+
+== PDF signature service
+
+Used by `decidim-initiatives`.
+
+Provide a class to process a pdf and return the document including a
+digital signature. The instances of this class are initialized with a hash
+containing the :pdf key with the pdf file content as value. The instances
+respond to a signed_pdf method containing the pdf with the signature.
+
+An example class would be something like:
+
+[source,ruby]
+....
+  class MyPDFSignatureService
+    attr_accessor :pdf
+
+    def initialize(args = {})
+      @pdf = args.fetch(:pdf)
+    end
+
+    def signed_pdf
+      # Code to return the pdf signed
+    end
+  end
+
+  config.pdf_signature_service = "MyPDFSignatureService"
+....
+
+==  Etherpad configuration
+
+
+Only needed if you want to have Etherpad integration with Decidim. See
+xref:services:etherpad.adoc[Etherpad's Decidim docs] in order to set it up.
+
+[source,ruby]
+....
+  config.etherpad = {
+    server: Rails.application.secrets.etherpad[:server],
+    api_key: Rails.application.secrets.etherpad[:api_key],
+    api_version: Rails.application.secrets.etherpad[:api_version]
+  }
+....
+
+== Default CSV column separator
+
+Sets Decidim::Exporters::CSV's default column separator
+
+[source,ruby]
+....
+  config.default_csv_col_sep = ";"
+....
+
+== User Roles
+
+The list of roles a user can have, not considering the space-specific roles.
+
+[source,ruby]
+....
+  config.user_roles = %w(admin user_manager)
+....
+
+== Visibility for Amendments
+
+The list of visibility options for amendments. An Array of Strings that
+serve both as locale keys and values to construct the input collection in Decidim::Amendment::VisibilityStepSetting::options.
+
+This collection is used in Decidim::Admin::SettingsHelper to generate a
+radio buttons collection input field form for a Decidim::Component
+step setting :amendments_visibility.
+
+
+[source,ruby]
+....
+  config.amendments_visibility_options = %w(all participants)
+....