RubyGems - decidim - Versions diffs - 0.30.2 → 0.31.0.rc1 - Mend

decidim 0.30.2 → 0.31.0.rc1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (82) hide show

data/docs/modules/develop/pages/endorsable.adoc DELETED Viewed

@@ -1,110 +0,0 @@
-= Endorsable
-== Things can be endorsable
-`Endorsable` is a feature to allow participants to promote (reivindicate, etc.) resources in the platform to their followers.
-When endorsing an element the endorsements counter for this element is increased and a notification to all the followers of the participant is sent.
-Participants can endorse with their own identity or with the identify of the `user_groups` they belong to. Each endorsing identity on its own will increment the endorsements counter by one.
-== Data model
-A `decidim_endorsements` table registers each endorsement that each identity gives to each element. This is, one endorsable has many endorsements, and each endorsement belongs to one endorsable.
-For performance, an endorsable has a counter cache of endorsements.
-[source,ascii]
-----
-+----------------------+
-|  Decidim::Endorsable |
-|   ((Proposal,...))   |                                   +-------------+
-+----------------------+  0..N +--------------------+   +--+Decidim::User|
-|-has_many endorsements|-------+Decidim::Endorsement|   |  +-------------+
-|#counter cache column |       +--------------------+   |
-|-endorsements_counter |       |-author: may be a   |<--+
-+----------------------+       |         user or a  |   |
-                               |         user_group |   |  +------------------+
-                               +--------------------+   +--+Decidim::UserGroup|
-                                                           +------------------+
-----
-Thus, each endorsable must have the endorsements counter cache column.
-This is an example migration to add the endorsements counter cache column to a resource:
-[source,ruby]
-----
-class AddEndorsementsCounterCacheToProposals < ActiveRecord::Migration[5.2]
-  def change
-    add_column :decidim_proposals_proposals, :endorsements_count, :integer, null: false, default: 0
-  end
-end
-----
-== Administration Panel
-It is a good practice to give the opportunity to the admin to switch Endorsements on and off.
-There are two switches that are normally defined in the manifest of the element in the following way (usually this would be at component.rb in a Decidim engine):
-[source,ruby]
-----
-    settings.attribute :endorsements_enabled, type: :boolean, default: true
-    settings.attribute :endorsements_blocked, type: :boolean
-----
-* `endorsements_enabled`: when enabled endorsement functionality appears in the public views, when disabled, this functionality is hidden.
-* `endorsements_blocked`: when blocked, the counter of endorsements is visible but no more endorsements can be added or withdrawn, the button is hidden.
-== Permissions
-In some cases, it may be interesting to require the user to be verified in order to be able to endorse. To do so, add the endorse action to the component manifest:
-[source,ruby]
-----
-  component.actions = %w(endorse vote create withdraw amend)
-----
-Given that some settings have been defined in the Administration Panel, for the user to have permissions to endorse endorsements should be enabled and not blocked.
-== Public view
-=== The "Endorse" buttons cell
-It normally appears in the resource detail view (show), at the bottom of the resource content, but above the comments when comments are enabled.
-It allows users to endorse with any of their identities, the personal one, and/or their user_groups', if any.
-It also shows the current number of endorsements for this resource.
-To render this button, `decidim-core` offers the `decidim/endorsement_buttons` cell. It is strongly recommended to use this cell to make new resources endorsable.
-[source,ruby]
-----
-  cell("decidim/endorsement_buttons", resource)
-----
-This cell will render the endorsement buttons depending on whether user endorsed the resource or not. The endorsements are labeled as *Likes*.
-[source,ruby]
-----
-  # By default the `show` method is invoked as usual
-  # Renders `render_endorsements_count` and `render_endorsements_button` in a block.
-  #
-  # It takes into account:
-  # - if endorsements are enabled
-  # - if users are logged in
-  # - if users require verification
-  #
-  cell("decidim/endorsement_buttons", resource)
-----
-=== The list of endorsers
-The `Decidim::EndorsersListCell` renders the list of endorsers of a resource. It is usually rendered in the show page of the resource, just upside the comments. Additionally, this cell also renders the pop-up required to view the endorsers of a certain resource.
-[source,ruby]
-----
-  # to render the list of endorsers, the cell requires the endorsable resource, and the current user
-  cell "decidim/endorsers_list", resource
-  # or using the helper
-  endorsers_list_cell(resource)
-----

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

@@ -1,257 +0,0 @@
-= Migrate to Webpacker an instance app
-In order to migrate an existing Decidim app to Webpacker, there are a few changes your need to run in your code.
-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 is recommended to understand how Webpacker works. More information:
-* https://github.com/rails/webpacker#usage[Webpacker README]
-* https://edgeguides.rubyonrails.org/webpacker.html[Rails Webpacker guide]
-== Requirements
-Before starting the migration, please check you have the following dependencies installed:
-- Node.js version 16.9.x (this version is mandatory)
-- Npm version 7.21.x (it works with other versions, but this is the recommended)
-- Decidim updated to at least v0.25.0.rc4
-== Guide
-=== Add Webpacker to the application
-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]
-----
-bundle exec rails webpacker:install
-----
-* Install Decidim webpacker custom code
-[source,console]
-----
-bundle exec rails decidim:webpacker:install
-----
-This task do a few steps to allow the Rails instance to have a webpacker instance sharing the code between itself and Decidim gem.
-This task is automatically performed every time decidim is updated, to get the latest Webpack configuration. This happens when you run the `decidim:upgrade` task.
-=== Copy Decidim custom CSS and JavaScript
-`webpacker:install` task should have created to you the following dirs structure:
-[source,console]
-----
-app/packs:
-  ├── entrypoints
-  └── src
-  └── stylesheets
-  └── images
-----
-If it is not the case you must create it. Then, copy Decidim customizable assets
-* Copy the file https://github.com/decidim/decidim/blob/develop/decidim-generators/lib/decidim/generators/app_templates/decidim_application.js[decidim_application.js] to `app/packs/src/decidim/decidim_application.js`
-* Copy the file https://github.com/decidim/decidim/blob/develop/decidim-generators/lib/decidim/generators/app_templates/decidim_application.scss[decidim_application.scss] to `app/packs/stylesheets/decidim/decidim_application.scss`
-* Copy the file https://github.com/decidim/decidim/blob/develop/decidim-generators/lib/decidim/generators/app_templates/_decidim-settings.scss[_decidim-settings.scss] to `app/packs/stylesheets/decidim/_decidim-settings.scss`
-These files are hooked into Decidim packs (specifically into decidim-core pack) and will be automatically included inside that pack when compiled.
-You can download these files directly with these commands:
-[source,console]
-----
-mkdir -p app/packs/src/decidim app/packs/stylesheets/decidim app/packs/images
-touch app/packs/src/decidim/.keep app/packs/stylesheets/decidim/.keep app/packs/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`
-[source,console]
-----
-cp -rp app/assets/images/* app/packs/images/
-----
-For instance, add the image "app/packs/images/test.png" in a view using the helper:
-[source,erb]
-----
-<%= image_pack_tag "media/images/test.png" %>
-----
-Note that, by default, all images are flattened in a single directory (any subdirectory structure is lost when requiring an image using the `image_pack_tag`).
-So, if you have a file in a subdirectory such as `app/packs/images/subfolder/test.png`, you still need to call for the image using `image_pack_tag "media/images/test.png"`
-=== Migrate stylesheets
-Existing stylesheets should be moved from `app/assets/stylesheets` to `app/packs/stylesheets` and imported with `@import` into `decidim_application.scss`. Take into account that you might need to adjust a bit the paths of the `@import` to adjust them to the new locations.
-If that CSS file is replacing a Decidim file, there is no need to add it to `decidim_application.scss`.
-If any of the CSS is re-defining CSS vars add them to `_decidim-settings.scss`.
-=== Migrate javascripts
-Existing javascripts should be moved from `app/assets/javascripts` 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 is no need to add it to `decidim_application.js`
-=== Update Rails helpers
-`javascript_include_tag` and `stylesheet_link_tag` have been replaced by `javascript_pack_tag` and `stylesheet_pack_tag`. This only needs to be done if you are modifying the `application.html` file or partial in your layout.
-For images, if they are in `app/packs/images` you need to replace `ìmage_tag` with `image_pack_tag`.
-=== Migrate vendorized files and gems
-Sometimes assets are included in `vendor/assets/` folder or imported from gems. For each specific one you should check:
-1. if the asset is a javascript that is available as npm package the recommendation is to add it to package.json with `npm install`. If it is 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.
-=== Migrate uploads to ActiveStorage
-The old method (CarrierWave) to handle user uploads has changed, now it uses ActiveStorage.
-This means that all the old files need to be migrated to the new system. Use the following rake task to perform this task:
-[source,console]
-----
-RAILS_ENV=production bin/rails decidim:active_storage_migrations:migrate_from_carrierwave_to_active_storage
-----
-=== Optional asset includes
-Decidim Webpacker provides a new configuration convention that allows you to add extra configurations for webpacker using a configuration file named `config/assets.rb`. Within this file, you have the following API methods available:
-[source,ruby]
-----
-# frozen_string_literal: true
-# This file is located at `config/assets.rb` of your module.
-# Define the base path of your module. Please note that `Rails.root` may not be
-# used because we are not inside the Rails environment when this file is loaded.
-base_path = File.expand_path("..", __dir__)
-# If you want to import some extra SCSS files in the Decidim main SCSS file
-# without adding any extra stylesheet inclusion tags, you can use the following
-# method to register the stylesheet import for the main application. This would
-# include an SCSS file at `app/packs/stylesheets/your_app_extensions.scss` into
-# the Decidim's main SCSS file.
-Decidim::Webpacker.register_stylesheet_import("stylesheets/your_app_extensions")
-# If you want to do the same but include the SCSS file for the admin panel's
-# main SCSS file, you can use the following method.
-Decidim::Webpacker.register_stylesheet_import("stylesheets/your_app_admin_extensions", group: :admin)
-----
-=== Remove Sprockets references
-The completely remove Sprockets references from your application:
-* Review your Gemfile and remove any reference to `sprockets` and `sassc-rails`
-* Remove `config/initializers/assets.rb`
-* Remove `app/assets` folder
-* In `config/application.rb` replace:
-[source,ruby]
-----
-require 'rails/all'
-----
-with:
-[source,ruby]
-----
-require "decidim/rails"
-# Add the frameworks used by your app that are not loaded by Decidim.
-# require "action_cable/engine"
-# require "action_mailbox/engine"
-# require "action_text/engine"
-----
-* In `config/environments/*.rb` remove any line containing `config.assets.*` (i.e `config.assets.debug = true`)
-=== 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.
-In the case of Capistrano this can be done with a before hook (can be added at the end of your `config/deploy.rb` file):
-[source,ruby]
-----
-namespace :deploy do
-  desc "Decidim webpacker configuration"
-  task :decidim_webpacker_install do
-    on roles(:all) do
-      within release_path do
-        execute :npm, "install"
-      end
-    end
-  end
-  before "deploy:assets:precompile", "deploy:decidim_webpacker_install"
-end
-----
-Also, in the case of Capistrano it is interesting to add to the shared_paths the following folders:
-* `storage` *IMPORTANT!*
-* `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 are using the correct Node.js and NPM versions.
-In some case it might be that some packages are not well resolved when installing NPM modules. If you get messages like:
-[source,console]
-----
-...
-[webpack-cli] Error: Cannot find module '@rails/webpacker'
-...
-----
-These might be due some kind of corruption in your `package-lock.json` file, you can try either to remove this file and recreate it with `npm install` or to add the package `@rails/webpacker` manually in your `package.json` file next to the `@decidim/webpacker` package:
-[source,json]
-----
-...
-    "@decidim/webpacker": "^0.25.2",
-    "@rails/webpacker": "^6.0.0-rc.5",
-...
-----
-Then execute `npm install`.

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

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

@@ -1,123 +0,0 @@
-= Metrics
-Metrics calculations must be executed everyday. Some `rake task` have been added to perform it.
-* To execute all metrics at once. Related to previous date from _today_
-+
-[source,ruby]
-----
-bundle exec rake decidim:metrics:all
-----
-* To execute an specific metric. Related to previous date from _today_
-+
-[source,ruby]
-----
-bundle exec rake decidim:metrics:one["<metric name>"]
-----
-* To execute metrics for a given date (all or an specific one)
-+
-[source,ruby]
-----
-bundle exec rake decidim:metrics:all["YYYY-MM-DD"]
-bundle exec rake decidim:metrics:one["<metric name>","YYYY-MM-DD"]
-----
-* It is possible to rebuild one or all metrics since some specific day. This is useful in case current metrics are no generated or corrupt. *Depending on the size of the database this can take a long time!*. The command will execute the same calculations as the commands above for *each* day between _today_ and the date specified.
-* To rebuild metrics since a given date (all or an specific one)
-+
-[source,ruby]
-----
-bundle exec rake decidim:metrics:rebuild["YYYY-MM-DD"]
-bundle exec rake decidim:metrics:rebuild["<metric name>","YYYY-MM-DD"]
-----
-== Available metrics
-* Use the command `decidim:metrics:list` to list all available metrics using the console:
-[source,ruby]
-----
-bundle exec rake decidim:metrics:list
-----
-Currently, available metrics are:
-* *users*, created `Users`
-* *proposals*, published, not withdrawn and not _hidden_ `Proposals`
-* *accepted_proposals*, accepted `Proposals`
-* *supports*, supports given to `Proposals`
-* *assemblies*, published `Assemblies`
-* *participatory_processes*, published `ParticipatoryProcesses`
-* *results*, `Results` in `Accountability`
-* *comments*, `Comments` generated by users, related to public elements and not _hidden_
-* *meetings*, public `Meetings`
-Only available for `ParticipatorySpaces` (restricted to `ParticipatoryProcesses`)
-* *participants*, unique users who make at least one of the following actions:
- ** Answer a survey
- ** Create a debate
- ** Create a proposal
- ** Endorse a proposal
- ** Leave a comment
- ** Support a proposal
- ** Vote a participatory budgeting project
-* *followers*, unique users who follow any participatory element in a `ParticipatorySpace`
-* *endorsements*, number of `Endorsements` in `Proposals`, within a `ParticipatorySpace`
-* *debates*, number of `Debates` within a `ParticipatorySpace`
-* *survey_answers*, number of answered `Surveys` by users within a `ParticipatorySpace`
-== Configuration
-* A *crontab* line must be added to your server to maintain them updated daily. You could use https://github.com/javan/whenever[Whenever] to manage it directly from the APP. You probably want to schedule a `bundle exec rake decidim:metrics:all` every night.
-* An *ActiveJob* queue, like https://github.com/mperham/sidekiq[Sidekiq] or https://github.com/collectiveidea/delayed_job/[DelayedJob]
-== Persistence
-The metrics module precomputes calculations and persists them into
-`decidim_metrics` database table. So this module only uses one single table to
-persist metrics from all times and types.
-The `decidim_metrics` table has the following fields:
-* `day`: the day for which the metric has been computed.
-* `metric_type`: the type of the metric. One of: users, proposals, accepted_proposals, supports, assemblies.
-* `cumulative`: quantity accumulated to day `"day`".
-* `quantity`:  quantity for the current day, `"day`".
-* `decidim_organization_id`: the FK to the organization to which this Metric belongs to.
-* `participatory_space_type` + `participatory_space_id`: the FK to the participatory space to which this Metric belongs to, if any.
-* `related_object_type` + `related_object_id`: the FK to the object to which this Metric belongs to, if any.
-* `decidim_category_id`: the FK to the category for this Metric, if any.
-Relations around `decidim_metrics` table:
-[source,ascii]
-----
-                                                    +------------------------+
-+--------------+                                    | ParticipatoryProcesses |
-| Organization |                               +----+------------------------+
-+------+-------+                               |
-       |            +--------------------+     |    +------------+
-       |            |                    |     +----+ Assemblies |
-       |     +----->+ ParticipatorySpace +<----+    +------------+
-       |     |      |                    |     |    +-------------+
-       |     |      +--------------------+     +----+ Initiatives |
-       |     |                                      +-------------+
-       |     |
-       |     |
- +-----+-------+---+
- |                 |
- | decidim_metrics |
- |                 |
- +--------+--------+       +----------------+
-          |                | related_object |
-          +--------------->+                |
-                           | [polymorphic]  |
-                           +----------------+
-----
-== Troubleshooting
-If you find problems in your metrics numbers you can follow the guide xref:develop:troubleshooting_metrics.adoc[Troubleshooting metrics].