decidim 0.9.3 → 0.10.0

data/README.md

@@ -41,77 +41,49 @@ Project management [[See on Waffle.io]](https://waffle.io/decidim/decidim)
 
 * [Get started with Decidim](#getting-started-with-decidim)
 * [Contribute to the project](#how-to-contribute)
-* [Officially supported modules](#officially-supported-modules)
-* [How to test Decidim engines](docs/testing.md)
+* [Modules](#modules)
 * [Create & browse development app](#browse-decidim)
-* [Technical tradeoffs](#technical-tradeoffs)
 
 ---
 
 ## Getting started with Decidim
 
-We've set up a guide on how to install, set up and upgrade Decidim. See the [Getting started guide](https://github.com/decidim/decidim/blob/master/docs/getting_started.md).
-
-## How to contribute
-
-### As a Translator
-
-Decidim is already translated on multiple languages (English, Spanish, Catalan, Basque, Galician, Italian, Finnish, Dutch, French, Portuguese (and Brazilian Portuguese), Swedish, Russian and Ukrainian). You can help us at [Crowdin, the translation service](https://crowdin.com/project/decidim), reviewing these translations or proposing a new language to add to the platform.
-
-### As a Developer
+TLDR: install gem, generate a Ruby on Rails app, enjoy.
 
-In order to develop on decidim, you'll need:
-
-* **Git** 2.15+
-* **PostgreSQL** 9.4+
-* **Ruby** 2.5.0 (2.3+ should work just fine, but that's the version we test against)
-* **NodeJS** 9.x.x (with `yarn` as a package manager)
-* **ImageMagick**
-* **Chrome** browser and [chromedriver](https://sites.google.com/a/chromium.org/chromedriver/).
-
-The easiest way to work on decidim is to clone decidim's repository and install its dependencies
-
-```bash
-git clone git@github.com:decidim/decidim.git
-cd decidim
-bundle install
-yarn install
+```console
+gem install decidim
+decidim decidim_application
 ```
 
-You have several rake tasks available:
-
-* `bundle exec rake development_app`: Creates a development app which you can use to run an application with the gems in your path.
-* `bundle exec rake test_app`: Generates a dummy application to be used for testing.
-* `bundle exec rake test_all`: Runs the tests of every engine using the dummy
-  application
+We've set up a guide on how to install, set up and upgrade Decidim. See the [Getting started guide](https://github.com/decidim/decidim/blob/master/docs/getting_started.md).
 
-#### Browse Decidim
+## How to contribute
 
-After you create a development app (`bundle exec rake development_app`):
+See [Contributing](CONTRIBUTING.md).
 
-* `cd development_app`
-* `bundle exec rails s`
-* Go to 'http://localhost:3000'
+### Browse Decidim
 
-Optionally, you can log in as: user@example.org | decidim123456
+After you create a development app (`bundle exec rake development_app`), you
+have to switch to it and boot the rails server with `cd development_app &&
+bundle exec rails s`.
 
-Also, if you want to verify yourself against the default authorization handler use a document number ended with "X".
+After that, you can:
 
-#### Browse Admin Interface
+* Browse the main interface at `http://localhost:3000`, and log in as: user@example.org | decidim123456
+* Browse the admin interface at `http://localhost:3000/admin`, and log in as: admin@example.org | decidim123456
+* Browse the system interface at `http://localhost:3000/system`, and log in as: system@example.org | decidim123456
 
-After you create a development app (`bundle exec rake development_app`):
+Also, if you want to verify yourself against the default authorization handler use a document number ended with "X".
 
-* `cd development_app`
-* `bundle exec rails s`
-* Go to 'http://localhost:3000/admin'
-* Login data: admin@example.org | decidim123456
+## Modules
 
-## Officially supported modules
+### Official (stable)
 
-| Library                                                                                                   | Description                                                                                                                                                  |
+| Module                                                                                                    | Description                                                                                                                                                  |
 | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [Accountability](https://github.com/decidim/decidim/tree/master/decidim-accountability)                   | Adds an accountability section to any participatory space so users can follow along the state of the accepted proposals.                                     |
 | [Admin](https://github.com/decidim/decidim/tree/master/decidim-admin)                                     | Adds an administration dashboard so users can manage their organization and all other entities.                                                              |
-| [API](https://github.com/decidim/decidim/tree/master/decidim-api)                                         | Exposes a GraphQL API to programatically interact with the Decidim platform via HTTP                                                                         |
+| [API](https://github.com/decidim/decidim/tree/master/decidim-api)                                         | Exposes a GraphQL API to programatically interact with the Decidim platform via HTTP.                                                                        |
 | [Assemblies](https://github.com/decidim/decidim/tree/master/decidim-assemblies)                           | Permanent participatory spaces.                                                                                                                              |
 | [Budgets](https://github.com/decidim/decidim/tree/master/decidim-budgets)                                 | Adds a participatory budgets system to any participatory space.                                                                                              |
 | [Comments](https://github.com/decidim/decidim/tree/master/decidim-comments)                               | The Comments module adds the ability to include comments to any resource which can be commentable by users.                                                  |
@@ -121,23 +93,31 @@ After you create a development app (`bundle exec rake development_app`):
 | [Meeting](https://github.com/decidim/decidim/tree/master/decidim-meetings)                                | The Meeting module adds meeting to any participatory space. It adds a CRUD engine to the admin and public view scoped inside the participatory space.        |
 | [Pages](https://github.com/decidim/decidim/tree/master/decidim-pages)                                     | The Pages module adds static page capabilities to any participatory space. It basically provides an interface to include arbitrary HTML content to any step. |
 | [Proposals](https://github.com/decidim/decidim/tree/master/decidim-proposals)                             | The Proposals module adds one of the main features of Decidim: allows users to contribute to a participatory space by creating proposals.                    |
-| [Accountability](https://github.com/decidim/decidim/tree/master/decidim-accountability)                   | Adds an accountability section to any participatory space so users can follow along the state of the accepted proposals.                                     |
 | [Surveys](https://github.com/decidim/decidim/tree/master/decidim-surveys)                                 | Adds the ability for admins to create arbitrary surveys.                                                                                                     |
-| [System](https://github.com/decidim/decidim/tree/master/decidim-system)                                   | Multitenant Admin to manage multiple organizations in a single installation                                                                                  |
+| [System](https://github.com/decidim/decidim/tree/master/decidim-system)                                   | Multitenant Admin to manage multiple organizations in a single installation.                                                                                 |
 
-## Technical tradeoffs
+### Official (on development)
 
-### Architecture
-
-This is not your typical Ruby on Rails Vanilla App. We've tried using [Consul](http://decide.es) but we found some problems on reutilization, adaptation, modularization and configuration. You can read more about that on "[Propuesta de Cambios de Arquitectura de Consul](https://www.gitbook.com/book/alabs/propuesta-de-cambios-en-la-arquitectura-de-consul/details)".
-
-### Turbolinks
-
-Decidim doesn't support `turbolinks` so it isn't included on our generated apps and it's removed for existing Rails applications which install the Decidim engine.
+| Module                                                                                                    | Description                                                                                                                                                  |
+| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [Blogs](https://github.com/decidim/decidim-module-blogs)                                                  |  This component makes possible to add posts ordered by publication time to spaces.                                                                           |
+| [Consultations](https://github.com/decidim/decidim-module-consultations)                                  |  This module creates a new space for decidim to host consultations: debates around critical questions and a proxy for eVoting                                |
+| [Initiatives](https://github.com/decidim/decidim-initiatives)                                             | Initiatives is the place on Decidim's where citizens can promote a civic initiative. Unlike participatory processes that must be created by an administrator, Civic initiatives can be created by any user of the platform.                                                                                             |
+| [Sortitions](https://github.com/decidim/decidim-module-sortitions)                                        |  This component makes possible to select randomly a number of proposals among a set of proposals (or a category of proposals within a set) maximizing guarantees of randomness and avoiding manipulation of results by the administrator.                                                                                               |
 
-The main reason is we are injecting some scripts into the body for some individual pages and Turbolinks loads the scripts in parallel. For some libraries like [leaflet](http://leafletjs.com/) it's very inconvenient because its plugins extend an existing global object.
+### Community
 
-The support of Turbolinks was dropped in [d8c7d9f](https://github.com/decidim/decidim/commit/d8c7d9f63e4d75307e8f7a0360bef977fab209b6). If you're interested in bringing turbolinks back, further discussion is welcome.
+| Module                                                                                                    | Description                                                                                                                                                  |
+| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [Census](https://github.com/diputacioBCN/decidim-diba/tree/master/decidim-census)                         | Allows to upload a census CSV file to perform authorizations against real users parameterised by their age.                                                  |
+| [Crowdfunding](https://github.com/podemos-info/decidim-module-crowdfundings)                              | This rails engine implements a Decidim feature that allows to the administrators to configure crowfunding campaigns for a participatory space.               |
+| [DataViz](https://github.com/AjuntamentdeBarcelona/decidim-barcelona/tree/master/decidim-dataviz)         | The Dataviz module adds the PAM data visualizations to any participatory process but it is intended to be used just for the PAM participatory process.       |
+| [Members](https://github.com/ElectricThings/decidim-members)                                              | Members list and search plugin for Decidim                                                                                                                   |
+| [Pol.is](https://github.com/OpenSourcePolitics/decidim-polis)                                             | Pol.is integration on Decidim                                                                                                                                |
+| [User Export](https://github.com/OpenSourcePolitics/decidim-user-export)                                  | Allow user export                                                                                                                                            |
+| [Verification DIBA Census API](https://github.com/diputacioBCN/decidim-diba/tree/master/decidim-diba_census_api)                                     | A decidim package to provice user authorizations agains the Diputació of Barcelona census API                     |
+| [Verification Podemos Census API](https://github.com/podemos-info/decidim-module-census_connector)        | A decidim package to provice user authorizations against the Podemos census API                                                                              |
+| [Votings](https://github.com/podemos-info/decidim-module-votings)                                         | An administrator can add one or more votings to a participatory process or assambly                                                                          |
 
 ## Following our license
 

data/Rakefile

@@ -30,19 +30,36 @@ end
 desc "Installs all gems locally."
 task :install_all do
   Decidim::ComponentManager.run_all(
-    "rake install:local",
-    out: File::NULL
+    "gem build %name && mv %name-%version.gem ..",
+    include_root: false
+  )
+
+  Decidim::ComponentManager.new(__dir__).run(
+    "gem build %name && gem install *.gem"
   )
 end
 
 desc "Uninstalls all gems locally."
 task :uninstall_all do
   Decidim::ComponentManager.run_all(
-    "gem uninstall %name -v %version --executables --force",
-    out: File::NULL
+    "gem uninstall %name -v %version --executables --force"
+  )
+
+  Decidim::ComponentManager.new(__dir__).run(
+    "rm decidim-*.gem"
   )
 end
 
+Decidim::ComponentManager.all_dirs(include_root: false) do |dir|
+  manager = Decidim::ComponentManager.new(dir)
+  name = manager.short_name
+
+  desc "Runs tests on #{name}"
+  task "test_#{name}" do
+    manager.run("rake")
+  end
+end
+
 desc "Pushes a new build for each gem."
 task release_all: [:update_versions, :check_locale_completeness, :webpack] do
   Decidim::ComponentManager.run_all("rake release")
@@ -53,31 +70,15 @@ task :check_locale_completeness do
   system({ "ENFORCED_LOCALES" => "en,ca,es", "SKIP_NORMALIZATION" => "true" }, "rspec spec/i18n_spec.rb")
 end
 
-desc "Generates a dummy app for testing"
-task :test_app do
-  dummy_app_path = File.expand_path(File.join(Dir.pwd, "spec", "decidim_dummy_app"))
+load "decidim-dev/lib/tasks/generators.rake"
 
-  Dir.chdir(__dir__) do
-    sh "rm -fR #{dummy_app_path}", verbose: false
-
-    Decidim::Generators::AppGenerator.start(
-      [dummy_app_path, "--path", "../..", "--recreate_db", "--demo"]
-    )
-  end
-end
+desc "Generates a dummy app for testing"
+task test_app: "decidim:generate_external_test_app"
 
 desc "Generates a development app."
-task :development_app do
-  Dir.chdir(__dir__) do
-    sh "rm -fR development_app", verbose: false
-  end
-
-  Decidim::Generators::AppGenerator.start(
-    ["development_app", "--path", "..", "--recreate_db", "--seed_db", "--demo"]
-  )
-end
+task development_app: "decidim:generate_external_development_app"
 
 desc "Build webpack bundle files"
 task :webpack do
-  sh "yarn install && yarn build:prod"
+  sh "npm install && npm run build:prod"
 end

data/docs/add_authenticable_action.md

@@ -0,0 +1,20 @@
+# How to add a new authenticable action?
+## Proposals example
+We're going to reproduce the steps to add an action (adhere) for a proposal step by step.
+### Configuring a new 'adhere' action
+1. Edit decidim-proposals/lib/decidim/proposals/feature.rb
+1. Add the new 'adhere' action into the `feature.actions` array and save the file:
+```
+feature.actions = %w(adhere vote create)
+```
+
+3. Translate the action for the corresponding key: `en.decidim.features.proposals.actions.adhere = Adhere`
+1. Edit `app/models/decidim/proposals/abilities/current_user_ability.rb` and add the corresponding cancancan ability like `can :adhere, Proposal do |_proposal| ...`.
+1. Restart the server to pick up the changes.
+1. Now the admin should be able to go to the Control Panel and edit `PROCESSES/Proposals/Permissions/Adhere` panel. There an `Authorization Handler` can be set.
+
+### Using the new 'adhere' action
+With a user which has the selected permission verified:
+1. Go to a Proposal detail in the front-end
+1. Adhere to the current proposal (see ProposalAdhesionsController): the user should be able to perform an adhesion.
+    - If the user had the required permission unverified, the 'adhere' button should block the action. You can check it with an unverified user.

data/docs/adding_fixtures_aka_dummy_content.md

@@ -0,0 +1,7 @@
+# How to add dummy content to a development application?
+## Proposals example
+1. In decidim-proposals open `lib/decidim/proposals/feature.rb`.
+1. Find the `feature.seeds do...` block.
+1. Create your dummy content as if you were in a `db/seed.rb` script.
+  - Take advantage of the Faker gem, already in decidim.
+  - You can use https://github.com/decidim/decidim/blob/master/decidim-core/lib/decidim/faker/localized.rb, which uses `Faker` internally, if you need content for i18n fields.

data/docs/advanced/activity_log.md

@@ -0,0 +1,138 @@
+# Activity log
+
+In order to make your component compatible with the activity log, you need to follow these steps:
+
+1. Make your model include the `Decidim::Traceable` module. This will let Decidim create versions every time your model records are changed. It uses [`paper_trail`](https://github.com/airblade/paper_trail) to generate the versions.
+1. Make your commands use `Decidim.traceability` to create and update records. Documentation can be found in `Decidim::Traceability`. This should set the author of the change in your record properly.
+
+That's all you need to do to get it working, really. We have a default way to present logs that Just Works™. Keep reading if you want to customize how the logs for your resources look!
+
+## The default renderer
+
+The default renderer doesn't know many things. It knows the author, what action was done, the resource affected and the space where the resource resides. When the resource is updated it shows the diff of all the fields that have been changed, with the old and new values for each field. values are not formatted in any specific way, so you might see some weirdly formatted values on the log diff: that's how it's rendered from the database.
+
+## Customizing the logs for your resources
+
+ The default presenter doesn't fulfill your needs? You might want to create your own presenter if you find yourself in one of these cases:
+
+- You want to show what type of resource is affected by the action log
+- The default renderer cannot find the correct field to render the resource name
+- You want to show more info
+- You want to change the order of the factors in the log sentence
+- You want to change the format of the values in the diff
+
+Let's go ahead and see how to create your own resource presenter.
+
+Custom presenters should be named as `Decidim::<your module name>::<log name>::<your model name>Presenter`. There's currently only one log, `AdminLog`. This means that if your model is `Decidim::Accountability::Result`, then your admin log presenter is must be `Decidim::Accountability::AdminLog::ResultPresenter`. You can inherit from `Decidim::Log::BasePresenter` for simplicity:
+
+```ruby
+module Decidim
+  module Accountability
+    module AdminLog
+      class ResultPresenter < Decidim::Log::BasePresenter
+      end
+    end
+  end
+end
+```
+
+Some examples with basic customization follow, although you can read the source code docs and overwrite any method you need.
+
+### Changing the action log sentence
+
+In order to change the default sentence to something that fits better to your resource, you can overwrite the `action_string` method in your presenter:
+
+```ruby
+module Decidim
+  module Accountability
+    module AdminLog
+      class ResultPresenter < Decidim::Log::BasePresenter
+        private
+
+        def action_string
+          case action
+          when "create"
+            "decidim.accountability.admin_log.result.create"
+          when "update"
+            "decidim.accountability.admin_log.result.update"
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+This is useful to show the resource type in the sentence.
+
+### Limiting what fields get presented in the diff
+
+By default, all changed fields are presented in the diff. In order to limit them, overwrite the `diff_fields_mapping` method in your custom presenter. It has to return a `Hash`, where keys are the name of the attributes and values are the presenters that render the attributes. **Limitations**: we can only show diffs for column fields, not dynamic methods, so the `diff_fields_mapping` only accepts column names.
+
+In this example, we're telling our presenter to only present the `start_date` as a date, the `title` as an i18n field, the `decidim_scope_id` with no particular presenter, and `progress` as a percentage:
+
+```ruby
+module Decidim
+  module Accountability
+    module AdminLog
+      class ResultPresenter < Decidim::Log::BasePresenter
+        private
+
+        def diff_fields_mapping
+          {
+            start_date: :date,
+            title: :i18n,
+            decidim_scope_id: :default,
+            progress: :percentage
+          }
+        end
+      end
+    end
+  end
+end
+```
+
+#### Value types presenters
+
+Decidim comes with some default value types presenters to be used in the diffs. They all live in `Decidim::Log::ValueTypes`, check the source code for the full list. These presenters are used with a symbol, but you can use your own value type presenter if you use a string:
+
+```ruby
+module Decidim
+  module Accountability
+    module AdminLog
+      class ResultPresenter < Decidim::Log::BasePresenter
+        private
+
+        def diff_fields_mapping
+          {
+            decidim_scope_id: "Decidim::Accountability::AdminLog::ValueTypes::MyCustomPresenter",
+          }
+        end
+      end
+    end
+  end
+end
+```
+
+Then you can write your own value presenter as:
+
+```ruby
+module Decidim
+  module Accountability
+    module AdminLog
+      module ValueTypes
+        class MyCustomPresenter < Decidim::Log::Valuetypes::DefaultPresenter
+          def present
+            return unless value
+            "My super duper value: #{value}"
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+## Multiple logs
+
+Although Decidim currently only has a log for the admin section, in the future we might need an activity log for the public part. It's easy to assume we might need to render the same data in different formats, so we need to differentiate the presenters for each log. The current system handles the case for multiple logs, although we only have one.

data/docs/{content_processors.md → advanced/content_processors.md}

@@ -8,7 +8,7 @@ The content parser class is used to process the text before it is saved to the d
 
 Register the content processor in an `initializer`:
 
-```
+```ruby
 Decidim.content_processors += [:special_words]
 ```
 

data/docs/advanced/deploy.md

@@ -0,0 +1,9 @@
+# Deploy
+
+## Self-hosted
+
+You can install Decidim like a regular Ruby on Rails application, with nginx, Passenger, rbenv and PostgreSQL. You should also configure a valid SMTP account to send emails and add the delayed_job gem and execute it so you can receive emails (ie on user registration).
+
+## Heroku
+
+You can follow an opinionated Rails generator to configure your decidim app so that it can be [deployed to Heroku](https://github.com/codegram/decidim-deploy-heroku).

data/docs/{create_followers_from_resource_authors.md → advanced/followers.md}

@@ -1,4 +1,19 @@
-# Create followers from resource authors
+# Followers
+
+## Create followers from comment authors
+
+Run the following script to make all comment authors follow the commented resource:
+
+```ruby
+Decidim::Comments::Comment.includes(:author, :root_commentable).find_each do |comment|
+  begin
+    Decidim::Follow.create!(followable: comment.root_commentable, user: comment.author)
+  rescue
+  end
+end; p 1
+```
+
+## Create followers from resource authors
 
 Run the following script to make all resource authors follow the resource:
 
@@ -17,3 +32,4 @@ Decidim.feature_manifests.each do |feature_manifest|
   end
 end; p 1
 ```
+

data/docs/advanced/how_to_create_a_module.md

@@ -0,0 +1,9 @@
+# How to create a Decidim component
+
+Use [decidim-generators](https://github.com/decidim/decidim-generators) to
+automatically generate a decidim component skeleton, or copy the basic structure
+of an existing mantained plugin.
+
+Upload the component to GitHub with the naming *decidim-module-<engine_name>*,
+so it's easier to find on the
+[dependency graph](https://github.com/decidim/decidim/network/dependents).