decidim 0.21.0 → 0.23.2

data/docs/advanced/machine_translation_service.md

@@ -0,0 +1,12 @@
+# 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.
+
+## Integrating with async services
+
+Some translation services are async, which means that some extra work is needed. This is the main overview:
+
+- The Translation service will only send the translation request. It should have a way to send what resource, field and target locale are related to that translation.
+- You'll need to create a custom controller in your application to receive the callback from the translation service when the translation is finished
+- From that new endpoint, find a way to find the related resource, field and target locale. Then start a `Decidim::MachineTranslationSaveJob` with that data. This job will handle how to save the data in the DB.
+

data/docs/advanced/metrics.md

@@ -37,6 +37,7 @@ Metrics calculations must be executed everyday. Some `rake task` have been added
 ```ruby
 bundle exec rake decidim:metrics:list
 ```
+
 Currently, available metrics are:
 
 - **users**, created `Users`
@@ -78,20 +79,17 @@ 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.
+- `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_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:
-```
+
+```ascii
                                                     +------------------------+
 +--------------+                                    | ParticipatoryProcesses |
 | Organization |                               +----+------------------------+

data/docs/advanced/newsletter_templates.md

@@ -0,0 +1,64 @@
+# Newsletter templates
+
+The newsletter templates allow the user to select a template amongst a set of of them, and use it as base to send newsletters. This allow for more customization on newsletter, tematic newsletters, etc.
+
+Code-wise, they use the content blocks system internally, so [check the docs](https://github.com/decidim/decidim/blob/master/docs/advanced/content_blocks.md) for that section first.
+
+## Adding a new template
+
+You'll first need to register the template as a content block, but specifying `:newsletter_template` as its scope:
+
+```ruby
+Decidim.content_blocks.register(:newsletter_template, :my_template) do |content_block|
+  content_block.cell "decidim/newsletter_templates/my_template"
+  content_block.settings_form_cell = "decidim/newsletter_templates/my_template_settings_form"
+  content_block.public_name_key "decidim.newsletter_templates.my_template.name"
+
+  content_block.images = [
+    {
+      name: :main_image,
+      uploader: "Decidim::NewsletterTemplateImageUploader",
+      preview: -> { ActionController::Base.helpers.asset_path("decidim/placeholder.jpg") }
+    }
+  ]
+
+  content_block.settings do |settings|
+    settings.attribute(
+      :body,
+      type: :text,
+      translated: true,
+      preview: -> { ([I18n.t("decidim.newsletter_templates.my_template.body_preview")] * 100).join(" ") }
+    )
+  end
+end
+```
+
+You'll need to add this into an initializer. Note that if you're adding this from a module, then you need to add it from the `engine.rb` file (check the docs for content blocks for more info).
+
+This is the simplest template. It has a single attribute, in this case a translatable chunk of text. Let's go line by line.
+
+Inside the block, first we define the path of the cell we'll use to render the email publicly. This cell will receive the `Decidim::ContentBlock` object, which will contain the attributes and any image we have (one in this example). In order to render cells, please note that emails have a very picky HTML syntax, so we suggest using some specialized tools to design the template, export the layout to HTML and render that through the cell. We suggest you make this cell inherit from `Decidim::NewsletterTemplates::BaseCell` for convenience.
+
+Then we define the cell that will be used to render the form in the admin section. This form needs to show inputs for the attributes defined when registering the template. It will receive the `form` object to render the input fields. We suggest this cell to inherit from `Decidim::NewsletterTemplates::BaseSettingsFormCell`.
+
+In the third line inside the block we define the I18n path to the public name of the template. This name will serve as identifier for the users who write the newsletters, so be sure to make it descriptive.
+
+After that we define the images this newsletter supports. We give it a unique name, the class name of the uploader we'll use (the example one is the default one, but you might want to customize this value) and a way to preview this image. This preview image will only be used in the "Preview" page of the template, it's not a fallback. If you want a fallback, please implement it through a custom uploader (see `carrierwave`'s docs for that). There's no limit of the amount of images you add.
+
+Finally, we define the attributes for the newsletter. In this case we define a body attribute, which is a translatable text. Whether this text require an editor or not will be defined by the settings cell. We also have a way to preview that attribute. There's no limit on the number of attributes you define.
+
+## Interpolating the recipient name
+
+Decidim accepts `%{name}` as a placeholder for the recipient name. If you want your template to use it, you'll need to call `parse_interpolations` in your public cell:
+
+```ruby
+class Decidim::NewsletterTemplates::MyTemplate < Decidim::ViewModel
+  include Decidim::NewslettersHelper
+
+  def body
+    parse_interpolations(uninterpolated_body, recipient_user, newsletter.id)
+  end
+end
+```
+
+The newsletter subject is automatically interpolated.

data/docs/advanced/notifications.md

@@ -0,0 +1,114 @@
+# Notifications
+
+In Decidim, notifications may mean two things:
+
+- he concept of notifying an event to a user. This is the wider use of "notification".
+- the notification's participant space, which lists the `Decidim::Notification`s she has received.
+
+So, in the wider sense, notifications are messages that are sent to the users, admins or participants, when something interesting occurs in the platform.
+
+Each notification is sent via two communication channels: email and internal notifications.
+
+## A Decidim Event
+
+Technically, a Decidim event is nothing but an `ActiveSupport::Notification` with a payload of the form
+
+```ruby
+ActiveSupport::Notifications.publish(
+  event,
+  event_class: event_class.name,
+  resource: resource,
+  affected_users: affected_users.uniq.compact,
+  followers: followers.uniq.compact,
+  extra: extra
+)
+```
+
+To publish an event to send a notification, Decidim's `EventManager` should be used:
+
+```ruby
+# Note the convention between the `event` key, and the `event_class` that will be used later to wrap the payload and be used as the email or notification model.
+data = {
+  event: "decidim.events.comments.comment_created",
+  event_class: Decidim::Comments::CommentCreatedEvent,
+  resource: comment.root_commentable,
+  extra: {
+    comment_id: comment.id
+  },
+  affected_users: [user1, user2],
+  followers: [user3, user4]
+}
+
+Decidim::EventsManager.publish(data)
+```
+
+Both, `EmailNotificationGenerator` and `NotificationGenerator` are use the same arguments:
+
+- **event**: A String with the name of the event.
+- **event_class**: A class that wraps the event.
+- **resource**: an instance of a class implementing the `Decidim::Resource` concern.
+- **followers**: a collection of Users that receive the notification because they're following it.
+- **affected_users**: a collection of Users that receive the notification because they're affected by it.
+- **force_send**: boolean indicating if EventPublisherJob should skip the `notifiable?` check it performs before notifying.
+- **extra**: a Hash with extra information to be included in the notification.
+
+Again, both generators will check for each user
+
+- in the *followers* array, if she has the `notification_types` set to "all" or "followed-only".
+- in the *affected_users* array, if she has the `notification_types` set to "all" or "own-only".
+
+Event names must start with "decidim.events." (the `event` data key). This way `Decidim::EventPublisherJob` will automatically process them. Otherwise no artifact in Decidim will process them, and will be the developer's responsibility to subscribe to them and process.
+
+Sometimes, when something that must be notified to users happen, a service is defined to manage the logic involved to decide which events should be published. See for example `Decidim::Comments::NewCommentNotificationCreator`.
+
+Please refer to [Ruby on Rails Notifications documentation](https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) if you need to hack the Decidim's events system.
+
+## How Decidim's `EventPublisherJob` processes the events?
+
+The `EventPublisherJob` in Decidim's core engine subscribes to all notifications matching the regular expression `/^decidim\.events\./`. This is, starting with "decidim.events.". It will then be invoked when an imaginary event named "decidim.events.harmonica_blues" is published.
+
+When invoked it simply performs some validations and enqueue an `EmailNotificationGeneratorJob` and a `NotificationGeneratorJob`.
+
+The validations it performs check if the resource, the component, or the participatory space are published (when the concept applies to the artifact).
+
+## The \*Event class
+
+Generates the email and notification messages from the information related with the notification.
+
+Event classes are subclasses of `Decidim::Events::SimpleEvent`.
+A subset of the payload of the notification is passed to the event class's constructor:
+
+- The `resource`
+- The `event` name
+- The notified user, either from the `followers` or from the `affected_users` arrays
+- The `extra` hash, with content specific for the given SimpleEvent subclass
+- The user_role, either :follower or :affected_user
+
+With the previous information the event class is able to generate the following contents.
+
+Developers will be able to customize those messages by adding translations to the `config/locales/en.yml` file of the corresponding module.
+The keys to be used will have the translation scope corresponding to the event name ("decidim.events.comments.comment_by_followed_user" for example) and the key will be the content to override (email_subject, email_intro, etc.)
+
+### Email contents
+
+The following are the parts of the notification email:
+
+- *email_subject*, to be customized
+- email_greeting, with a good default, usually there's no need to cusomize it
+- *email_intro*, to be customized
+- *resource_text* (optional), rendered `html_safe` if present
+- *resource_url*, a link to the involved resource if resource_url and resource_title are present
+- *email_outro*
+
+All contents except the `email_greeting` use to require customization on each notification.
+
+### Notification contents
+
+Only the `notification_title` is generated in the event class. The rest of the contents are produced by the templates from the `resource` and the `notification` objects.
+
+## Testing notifications
+
+- Test that the event has been published (usually a command test)
+- Test the event returns the expected contents for the email and the notification.
+
+Developers should we aware when adding URLs in the email's content, be sure to use absolute URLs and not relative paths.

data/docs/advanced/permissions.md

@@ -0,0 +1,23 @@
+# Permissions
+
+Since Decidim has multiple roles, we needed a permissions system to discover what actions can a user perform, given their roles. The basis of the current permissions system were added on [\#3029](https://github.com/decidim/decidim/pull/3029), so be sure to check that PR (and the related ones) to read the discussion and the motivations behind the change.
+
+## Overview
+
+When checking for permission to perform an action, we check this chain:
+
+1. The component permissions
+1. The participatory space permissions
+1. The core permissions
+
+This way we're going from more specific to more general.
+
+## Explanation
+
+We wrap the permission and its context in a `PermissionsAction` object. It also holds the state of the permission (whether it's been allowed or not).
+
+Each component and space must define a `Permissions` class, inheriting from `Decidim::DefaultPermissions`. The `Permissions` class must define a `permissions` instance method. this class will receive the permission action, and the `permissions` method must return the permission action. The `Permissions` class can set the action as allowed or disallowed.
+
+There's a small limitation in the permission action state machine: once it's been disallowed it can't be reallowed. This is to avoid mischievous modules modifying permissions.
+
+Permission actions have a scope. It's usually either `:public` or `:admin`, and the `Permissions` class usually handles the `:public` scope, while it delegates the `:admin` one to another specialized class.

data/docs/advanced/profiling.md

@@ -0,0 +1,43 @@
+# How to profile a Decidim app
+
+The developmen_app includes a bunch of gems that profile the application. Run the following command in the decidim root's folder:
+
+```bash
+bundle exec rake development_app
+```
+
+and then move into it and boot the server
+
+```bash
+cd developmen_app
+bundle exec rails s
+```
+
+## Bullet
+
+Bullet detects N+1 queries and suggests how to fix them, although it doesn't catch them all. It's currently configured in `config/initializers/bullet.rb` to log in the regular rails log and also in its own `log/bullet.log`. You'll now see entries like the following:
+
+```bash
+user: xxx
+GET /
+USE eager loading detected
+  Decidim::Comments::Comment => [:author]
+  Add to your query: .includes([:author])
+Call stack
+```
+
+It also warns you when there's an unnecessary eager load.
+
+More details: https://github.com/flyerhzm/bullet
+
+## Rack-mini-profiler
+
+This gem can analyze memory, database, and call stack with flamegraphs. It will show up in development on the top left corner and it gives you all sorts of profiling insights about that page. It'll tell you where the response time was spend on in the call stack.
+
+This gem is further enhanced with the `flamegraph`, `stackprof` and `memory_profiler` gems which provide more detailed analysis. Try out by appending `?pp=flamegraph`, `?pp=profile-gc` or `?pp=analyze-memory` to the URL. You can read more about these options at https://github.com/MiniProfiler/rack-mini-profiler#flamegraphs.
+
+More details: https://github.com/MiniProfiler/rack-mini-profiler
+
+## Profiling best practices
+
+You need to take the insights of these gems with a grain of salt though, if you run this in development. Rails' development settings have nothing to do with a production set up where classes are not reloaded and assets are precompiled and served from a web server. Therefore, you should mimic these settings as much as possible if you want your findings to be realistic.

data/docs/advanced/releases.md

@@ -0,0 +1,114 @@
+# Releasing new versions
+
+In order to release new version you need to be owner of all the gems at RubyGems, ask one of the owners to add you before releasing. (Try `gem owner decidim`).
+
+Remember to follow the Gitflow branching workflow.
+
+## Create the stable branch for the release
+
+1. Go to develop with `git checkout develop`
+1. Create the release branch `git checkout -b release/x.y.z-stable && git push origin release/x.y.z-stable`.
+1. If required, add the release branch to Crowdin so that any pending translations will generate a PR to this branch.
+
+Mark `develop` as the reference to the next release:
+
+1. Go back to develop with `git checkout develop`
+1. Turn develop into the `dev` branch for the next release:
+    1. Update `.decidim-version` to the new `dev` development version: `x.y.z.dev`, where `x.y.z` is the new semver number for the next version
+    1. Run `bin/rake update_versions`, this will update all references to the new version.
+    1. Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
+    1. Run `bin/rake webpack`, this will update the JavaScript bundle.
+1. Update `SECURITY.md` and change the supported version to the new version.
+1. Update the `CHANGELOG.MD`. At the top you should have an `Unreleased` header with the `Added`, `Changed`, `Fixed` and `Removed` empty sections. After that, the header with the current version and link with the same beforementioned sections and a `Previous versions` header at the bottom that links to the previous minor release stable branch.
+
+  ```markdown
+  ## [Unreleased](https://github.com/decidim/decidim/tree/HEAD)
+
+  ### Added
+
+  ### Changed
+
+  ### Fixed
+
+  ### Removed
+
+  ## [v0.XX.0](https://github.com/decidim/decidim/releases/tag/v0.XX.0)
+
+  ### Added
+  ...
+
+  ## Previous versions
+
+  Please check [0.XX-stable](https://github.com/decidim/decidim/blob/release/0.XX-stable/CHANGELOG.md) for previous changes.
+  ```
+
+1. Push the changes `git add . && git commit -m "Bump develop to next release version" && git push origin develop`
+
+## Release Candidates
+
+Release Candidates are the same as beta versions. They should be ready to go to production, but publicly released just before in order to be widely tested.
+
+If this is a **Release Candidate version** release, the steps to follow are:
+
+1. Checkout the release stable branch `git checkout release/x.y-stable`.
+1. Update `.decidim-version` to the new version `x.y.z.rc1`
+1. Run `bin/rake update_versions`, this will update all references to the new version.
+1. Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
+1. Run `bin/rake webpack`, this will update the JavaScript bundle.
+1. Commit all the changes: `git add . && git commit -m "Bump to rcXX version" && git push origin release/x.y-stable`.
+1. Tag the release candidate with `git tag vX.Y.Z.rcN && git push origin vX.Y.Z.rcN`.
+1. Usually, at this point, the release branch is deployed to meta-decidim during, at least, one week to validate the stability of the version.
+
+### During the validation period
+
+1. During the validation period, bugfixes must be implemented directly to the current `release/x.y.z-stable` branch and ported to `develop`.
+1. During the validation period, translations to the officially supported languages must be added to Crowdin and, when completed, merged into `release/x.y.z-stable`.
+
+## Major/Minor versions
+
+Release Candidates will be tested in a production server (usually meta-decidim) during some period of time (a week at least), when they are considered ready, it is time for them to be merged into `master`:
+
+1. Checkout the release stable branch `git checkout release/x.y-stable`.
+1. Update `.decidim-version` by removing the `.rcN` suffix, leaving a clean version number like `x.y.z`
+1. Run `bin/rake update_versions`, this will update all references to the new version.
+1. Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
+1. Run `bin/rake webpack`, this will update the JavaScript bundle.
+1. Commit all the changes: `git add . && git commit -m "Bump to v0.XX.0 final version" && git push origin release/x.y-stable`.
+1. Create the PR for the new version.
+    1. `git checkout master && git checkout -b release/x.y.z`
+    1. `git merge release/x.y-stable`
+    1. `git checkout --theirs *`
+    1. `git checkout --theirs .github/* \.*`
+    1. Review changes in `CHANGELOG.md`, manually update and create a "changelog" commit if required.
+    1. `git push origin release/x.y.z`
+    1. Create the PR. The base for this PR should be `master`, but GitHub may crash if there are a lot of changes. As a workaround create the branch against `develop` and, when created, change the base to `master`.
+    1. Still don't merge it.
+1. Before merging the PR to upgrade `master`, check that the stable branch for the previous version exists. For instance, if we are going to release v0.22.0, there should be a `release/0.21-stable` branch in the repository. If such branch does not exists, it has to be created now, before merging the new release. So, if this is the release of v0.22.0, branch off `release/0.21-stable` from `master`. These stable branches will be able to receive bugfixes, backports and will be the origin of patch releases for older releases.
+1. Merge (after proper peer review) the PR to `master` and remove `release/x.y.z` branch.
+1. Run `git checkout master && bin/rake release_all`, this will create all the tags, push the commits and tags and release the gems to RubyGems.
+1. Once all the gems are published you should create a new release at this repository, just go to the [releases page](https://github.com/decidim/decidim/releases) and create a new one.
+1. Create the stable branch for the current version. From `master`: `git checkout -b release/x.y-stable && git push origin release/x.y-stable`.
+1. Update Decidim's Docker repository as explained in the Docker images section below.
+1. Update Crowdin synchronization configuration with Github:
+    1. Add the new `release/x.y-stable` branch.
+    1. Remove from Crowdin branches that are not officially supported anymore. That way they don't synchronize with Github.
+1. Update the `CHANGELOG.MD` in `release/x.y-stable`. At the top you should have an `Unreleased` header with the `Added`, `Changed`, `Fixed` and `Removed` empty sections. After that, the header with the current version. Add the `Unreleased` section or create the new current version section.
+
+## Releasing patch versions
+
+Releasing new versions from a ***release/x.y-stable*** branch is quite easy. The process is very similar from releasing a new Decidim version:
+
+1. Checkout the branch you want to release: `git checkout -b release/x.y-stable`
+1. Update `.decidim-version` to the new version number.
+1. Run `bin/rake update_versions`, this will update all references to the new version.
+1. Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
+1. Run `bin/rake webpack`, this will update the JavaScript bundle.
+1. Update `CHANGELOG.MD`. At the top you should have an `Unreleased` header with the `Added`, `Changed`, `Fixed` and `Removed` empty sections. After that, the header with the current version and link like `## [0.20.0](https://github.com/decidim/decidim/tree/v0.20.0)` and again the headers for the `Added`, `Changed`, `Fixed` and `Removed` sections.
+1. Commit all the changes: `git add . && git commit -m "Prepare VERSION release"`
+1. Run `bin/rake release_all`, this will create all the tags, push the commits and tags and release the gems to RubyGems.
+1. Once all the gems are published you should create a new release at this repository, just go to the [releases page](https://github.com/decidim/decidim/releases) and create a new one.
+1. Update Decidim's Docker repository as explained in the Docker images section.
+
+## Docker images for each release
+
+1. After each release, you should update our [Docker repository](https://github.com/decidim/docker) so new images are build for the new release. To do it, just update `DECIDIM_VERSION` at [circle.yml](https://github.com/decidim/docker/blob/master/circle.yml).

data/docs/advanced/share_tokens.md

@@ -0,0 +1,53 @@
+# Share tokens
+
+Share tokens can be assigned to any model to provide a system to share unpublished resources with expirable and manageable tokens.
+
+A share token is created by a user with an expiration time, and can be added as a query param to access otherwise restricted locations.
+
+## Add share tokens to a model
+
+The model must `include Decidim::ShareableWithToken` and implement `shareable_url(share_token)`, which should return the public url for the resource you want to share, including the token as a query parameter.
+
+```ruby
+# Public: Public URL for your_resource with given share token as query parameter
+def shareable_url(share_token)
+  your_resource_public_path(self, share_token: share_token.token)
+end
+```
+
+## Set permissions
+
+You should change permissions logic for the resource to check if there's a `share_token` query parameter in the request url, and call `Decidim::ShareToken.use!` to both check if the token is valid, and if it is, to *use it* (which increments `times_used` variable and sets `last_used_at` to current time).
+
+It should do something similar to this:
+
+```ruby
+token = context[:share_token]
+
+return unless token.present?
+
+allow! if Decidim::ShareToken.use!(token_for: your_resource, token: token)
+```
+
+## Manage tokens
+
+Render the partial `decidim-admin/app/views/decidim/admin/share_tokens/_share_tokens.html.erb` inside a view, with:
+
+```ruby
+locals: { share_tokens: your_share_tokens_variable }
+```
+
+to let admins see and manage tokens for that resource.
+
+## Link to url with token
+
+Implement a `share` action (see below) in the resource controller (admin scope), redirecting to a url with a newly generated token, so you can call `share_my_resource_url`.
+
+```ruby
+def share
+  @your_resource = YourResource.find(params[:id]) # or whatever
+  share_token = @your_resource.share_tokens.create!(user: current_user, organization: current_organization)
+
+  redirect_to share_token.url
+end
+```