decidim 0.8.4 → 0.9.0

data/README.md

@@ -41,7 +41,7 @@ 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)
-* [Decidim components](#officially-supported-libraries)
+* [Officially supported modules](#officially-supported-modules)
 * [How to test Decidim engines](docs/testing.md)
 * [Create & browse development app](#browse-decidim)
 * [Technical tradeoffs](#technical-tradeoffs)
@@ -56,7 +56,7 @@ We've set up a guide on how to install, set up and upgrade Decidim. See the [Get
 
 ### As a Translator
 
-Decidim is already translated on multiple languages (English, Spanish, Catalan, Basque, Italian, Finnish, Dutch, French, 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.
+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
 
@@ -64,7 +64,7 @@ In order to develop on decidim, you'll need:
 
 * **Git** 2.15+
 * **PostgreSQL** 9.4+
-* **Ruby** 2.4.1
+* **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/).
@@ -106,24 +106,24 @@ After you create a development app (`bundle exec rake development_app`):
 * Go to 'http://localhost:3000/admin'
 * Login data: admin@example.org | decidim123456
 
-## Officially supported libraries
-
-| Library        | Description           |
-| ------------- |-------------|
-| [Admin](https://github.com/decidim/decidim/tree/master/decidim-admin)      | This library adds an administration dashboard so users can manage their organization and all other entities. |
-| [API](https://github.com/decidim/decidim/tree/master/decidim-api)      | This library 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. Currently in beta as an optional feature, can be included by explicitly adding `decidim-assemblies` to the Gemfile. |
-| [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.      |
-| [Core](https://github.com/decidim/decidim/tree/master/decidim-core) | The basics of Decidim: users, organizations, etc. This is the only required engine to run Decidim, all the others are optional. |
-| [Participatory Processes](https://github.com/decidim/decidim/tree/master/decidim-participatory_processes) | The main concept of a Decidim installation: participatory processes. |
-| [Dev](https://github.com/decidim/decidim/tree/master/decidim-dev) | This gem aids the local development of Decidim's features. |
-| [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 |
+## Officially supported modules
+
+| Library                                                                                                   | Description                                                                                                                                                  |
+| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [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                                                                         |
+| [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.                                                  |
+| [Core](https://github.com/decidim/decidim/tree/master/decidim-core)                                       | The basics of Decidim: users, organizations, etc. This is the only required engine to run Decidim, all the others are optional.                              |
+| [Participatory Processes](https://github.com/decidim/decidim/tree/master/decidim-participatory_processes) | The main concept of a Decidim installation: participatory processes.                                                                                         |
+| [Dev](https://github.com/decidim/decidim/tree/master/decidim-dev)                                         | Aids the local development of Decidim's features.                                                                                                            |
+| [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                                                                                  |
 
 ## Technical tradeoffs
 

data/Rakefile

@@ -3,93 +3,54 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require "generators/decidim/app_generator"
-require "generators/decidim/docker_generator"
-
-DECIDIM_GEMS = %w(core system admin api participatory_processes assemblies pages meetings proposals comments accountability budgets surveys verifications dev).freeze
+require "decidim/component_manager"
 
 RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec
 
 desc "Runs all tests in all Decidim engines"
-task :test_all do
-  tested_gems = DECIDIM_GEMS - ["dev"]
-
-  dirs = [__dir__] + tested_gems.map { |name| "#{__dir__}/decidim-#{name}" }
+task test_all: [:test_main, :test_subgems]
 
-  dirs.each do |dir|
-    Dir.chdir(dir) do
-      puts "Running #{File.basename(dir)}'s tests..."
-      status = system "rake"
-      abort unless status || ENV["FAIL_FAST"] == "false"
-    end
-  end
+desc "Runs all tests in decidim subgems"
+task test_subgems: :test_app do
+  Decidim::ComponentManager.run_all("rake", include_root: false)
 end
 
-def replace_file(name, regexp, replacement)
-  new_content = File.read(name).gsub(regexp, replacement)
-
-  File.open(name, "w") { |f| f.write(new_content) }
-end
-
-def version
-  File.read("#{__dir__}/.decidim-version").strip
+desc "Runs all tests in the main decidim gem"
+task :test_main do
+  Decidim::ComponentManager.new(__dir__).run("rake")
 end
 
 desc "Update version in all gems to the one set in the `.decidim-version` file"
 task :update_versions do
-  replace_file(
-    "#{__dir__}/package.json",
-    /^  "version": "[^"]*"/,
-    "  \"version\": \"#{version.gsub(/\.pre/, "-pre")}\""
-  )
-
-  DECIDIM_GEMS.each do |name|
-    replace_file(
-      "#{__dir__}/decidim-#{name}/lib/decidim/#{name}/version.rb",
-      /def self\.version(\s*)"[^"]*"/,
-      "def self.version\\1\"#{version}\""
-    )
-  end
-
-  replace_file(
-    "#{__dir__}/lib/decidim/version.rb",
-    /def self\.version(\s*)"[^"]*"/,
-    "def self.version\\1\"#{version}\""
-  )
+  Decidim::ComponentManager.replace_versions
 end
 
 desc "Installs all gems locally."
 task :install_all do
-  system "rake install:local"
-  DECIDIM_GEMS.each do |name|
-    Dir.chdir("#{__dir__}/decidim-#{name}") do
-      system "rake install:local"
-    end
-  end
+  Decidim::ComponentManager.run_all(
+    "rake install:local",
+    out: File::NULL
+  )
 end
 
 desc "Uninstalls all gems locally."
 task :uninstall_all do
-  system("gem uninstall decidim -v #{version} --executables --force")
-  DECIDIM_GEMS.each do |name|
-    system("gem uninstall decidim-#{name} -v #{version} --executables --force")
-  end
+  Decidim::ComponentManager.run_all(
+    "gem uninstall %name -v %version --executables --force",
+    out: File::NULL
+  )
 end
 
 desc "Pushes a new build for each gem."
 task release_all: [:update_versions, :check_locale_completeness, :webpack] do
-  sh "rake release" rescue nil
-  DECIDIM_GEMS.each do |name|
-    Dir.chdir("#{__dir__}/decidim-#{name}") do
-      sh "rake release" rescue nil
-    end
-  end
+  Decidim::ComponentManager.run_all("rake release")
 end
 
 desc "Makes sure all official locales are complete and clean."
 task :check_locale_completeness do
-  system({ "ENFORCED_LOCALES" => "en,ca,es" }, "rspec spec/i18n_spec.rb")
+  system({ "ENFORCED_LOCALES" => "en,ca,es", "SKIP_NORMALIZATION" => "true" }, "rspec spec/i18n_spec.rb")
 end
 
 desc "Generates a dummy app for testing"
@@ -98,9 +59,7 @@ task :test_app do
 
   Dir.chdir(__dir__) do
     sh "rm -fR #{dummy_app_path}", verbose: false
-  end
 
-  Bundler.with_clean_env do
     Decidim::Generators::AppGenerator.start(
       [dummy_app_path, "--path", "../..", "--recreate_db", "--demo"]
     )
@@ -113,22 +72,9 @@ task :development_app do
     sh "rm -fR development_app", verbose: false
   end
 
-  Bundler.with_clean_env do
-    Decidim::Generators::AppGenerator.start(
-      ["development_app", "--path", "..", "--recreate_db", "--seed_db", "--demo"]
-    )
-  end
-end
-
-desc "Generates a development app based on Docker."
-task :docker_development_app do
-  docker_app_path = __dir__ + "/docker_development_app"
-
-  Bundler.with_clean_env do
-    Decidim::Generators::DockerGenerator.start(
-      ["docker_development_app", "--docker_app_path", docker_app_path]
-    )
-  end
+  Decidim::Generators::AppGenerator.start(
+    ["development_app", "--path", "..", "--recreate_db", "--seed_db", "--demo"]
+  )
 end
 
 desc "Build webpack bundle files"

data/docs/content_processors.md

@@ -0,0 +1,58 @@
+# Content processors
+
+A content processor is a concept to refer to a set of two classes: a content parser class and a content renderer class.
+
+The content parser class is used to process the text before it is saved to the database, and the associated renderer class is used to render the saved content.
+
+## How do I add a content processor?
+
+Register the content processor in an `initializer`:
+
+```
+Decidim.content_processors += [:special_words]
+```
+
+Declare the parser class:
+
+```rb
+class Decidim::ContentParsers::SpecialWordsParser < BaseParser
+  Metadata = Struct.new(:count)
+
+  def rewrite
+    content.gsub('foo', '~~foo~~')
+  end
+
+  def metadata
+    Metadata.new(content.scan('foo').size)
+  end
+end
+```
+
+And the renderer class:
+
+```rb
+class Decidim::ContentRenderers::SpecialWordsRenderer < BaseRenderer
+  def render
+    content.gsub(/\~\~(.*?)\~\~/, '<del>\1</del>')
+  end
+end
+```
+
+## How to use the content parser class
+
+```rb
+parser = Decidim::ContentParsers::SpecialWordsParser.new(content)
+parser.rewrite # returns the content rewritten
+parser.metadata # returns a Metadata object
+```
+
+## How to use the content renderer class
+
+```rb
+renderer = Decidim::ContentRenderers::SpecialWordsRenderer.new(content)
+parser.render # returns the content formatted
+```
+
+## Additional documentation
+
+You can check the docs in the base classes and the user processor.

data/docs/customization/authorizations.md

@@ -0,0 +1,17 @@
+# Authorizations
+
+One particular thing about this kind of applications is the need to Authorize a given user. This is specially important when you want to have legally bindings decisions taken on the platform. There are several ways that this could be done:
+
+* By sending a SMS code to users to verify that their have a valid cellphone
+
+* By allowing users to upload a photo or scanned image of their identity document
+
+* By sending users a code through postal code
+
+* By allowing users to go to to a physical office and check their documentation
+
+* By checking some information through other systems (as a Municipal Census on the case of Municipalities, Cities or Towns)
+
+* By having a list of valid users emails
+
+Right now Decidim supports only a few of these cases, but we have an internal API where you can program your own kind of verifications. You can go see some example code, read more about how to work with Decidim modules, or even see how it’s done for Decidim Barcelona, the Barcelona City Council.

data/docs/customization/code.md

@@ -0,0 +1,28 @@
+# Code
+
+Decidim is multiple things:
+
+* A command line utility, which can create an application
+* A set of libraries, that the application can use
+
+Most of the time, you should work with the generated application. That application (development_app on this docs) should be named as your project, for instance for Barcelona City Council is `DecidimBarcelona`, so for creating it should be:
+
+```
+decidim DecidimBarcelona
+```
+
+If you want to override/change anything (for instance the homepage), you can just do it with the same name of the file, through Monkey Patching.
+
+If you want to extend Decidim, the prefered way should be by having a Module. This is a Ruby on Rails Engine which provides ruby code (models, views, controllers, assets, etc). You can use it through multiple ways:
+
+* Putting it on the same directory as your app and pointing on the Gemfile. [See example on GitHub](https://github.com/AjuntamentdeBarcelona/decidim-barcelona/tree/c210b5338d7ba1338c9879627e081da1441f1946). For instance:
+```
+gem "decidim-debates", path: "decidim-debates"
+```
+
+* Publishing on a git reposotory and pointing in on the Gemfile. For instance:
+```
+gem "decidim-consultations", git: "https://github.com/decidim/decidim-module-consultations"
+```
+
+* Publishing it on rubygems.org

data/docs/customization/gemfile.md

@@ -0,0 +1,11 @@
+# Gemfile
+
+You can add and change your Gemfile as you want, this is a classic Ruby on Rails application. For example to add[ rails-footnotes](https://github.com/josevalim/rails-footnotes) gem you would just add:
+
+```
+gem 'rails-footnotes', '~> 4.0'
+```
+
+And then just do the classic Ruby on Rails flow bundle install and following any gem specific install steps from its own documentation.
+
+You may also be interested on Adding a Decidim module.

data/docs/customization/images.md

@@ -0,0 +1,7 @@
+# Images
+
+You can change most of the images (for instance the logo, main banner on homepage, contents of participatory processes, etc) through the Administration panel.
+
+If you want to override the standard images given by Decidim (for instance the initial image for user’s avatars) you can do it by naming it the same way as the original image, in this case it should be `app/assets/images/decidim/default-avatar.svg`
+
+If you want to add a new image you can do it as any Rails application, leaving it on your image’s asset folder and using image_tag helper. You can see more documentation on [Rails guide](http://guides.rubyonrails.org/asset_pipeline.html).

data/docs/customization/javascript.md

@@ -0,0 +1,9 @@
+# Javascript
+
+If you want to add some custom Javascript code, just add it to app/assets/javascripts/application.js. For example to create a new alert just add:
+
+```
+$(function(){
+  alert('foobar');
+});
+```

data/docs/customization/styles.md

@@ -0,0 +1,15 @@
+# CSS Styles with SASS
+
+One of the first things you’ll want to do after you install Decidim is applying your own corporative image. To do this, you can go to app/assets/stylesheets/application.css.sass on your generated application with your own colors. There you can override any class using CSS with SASS.
+
+We use [SASS, with SCSS syntax](http://sass-lang.com/guide) as CSS preprocessor.
+
+Also you can check your scss files syntax with
+
+```
+scss-lint
+```
+
+## **Accesibility**
+
+To maintain accesibility level, if you add new colors use a[ Color contrast checker](http://webaim.org/resources/contrastchecker/) (WCAG AA is mandatory, WCAG AAA is recommended)

data/docs/customization/texts.md

@@ -0,0 +1,15 @@
+# Custom Texts
+
+You can change most of the texts through the Administration panel.
+
+If you want to change a given text that isn’t on the Administration panel, and belongs on Decidim code, you should first find out which key is being used. For instance, we want to change the home page text where it says "Let's build a more open, transparent and collaborative society.", we would search the text (using [github](https://github.com/decidim/decidim/search?utf8=%E2%9C%93&q=%22Let%27s+build+a+more+open%2C+transparent+and+collaborative+society.%22&type= ) or grep) and then I’d extract that key and their parents. On this case it’d be:
+
+```yml
+en:
+  pages:
+    home:
+      footer_sub_hero:
+        footer_sub_hero_body: Let's build a more open, transparent and collaborative society.<br /> Join, participate and decide.
+```
+
+We need to create a file for this translation as Rails documentation says, for instance config/locales/home.en.yml

data/docs/customization/views.md

@@ -0,0 +1,5 @@
+# Views (HTML)
+
+If you want to add a new HTML page, you can do this by working as a regular Rails application.
+
+If you want to override a view or partial given by Decidim you can do this just by naming it with the same filename that you already have.

data/docs/getting_started.md

@@ -35,6 +35,7 @@ Afterwards, you can create an application with the nice `decidim` executable:
 ```
 $ decidim decidim_application
 $ cd decidim_application
+$ bundle install
 ```
 
 ### Initializing your app for local development
@@ -78,8 +79,6 @@ We also have other guides on how to configure some extra features:
 
 ## Deploy
 
-Once you've generated the Decidim app you might need to do some changes in order to deploy it. You can check [`codegram/decidim-deploy-heroku`](https://github.com/codegram/decidim-deploy-heroku) for an opinionated example of things to do before deploying to Heroku, for example.
-
 Once you've successfully deployed your app to your favorite platform, you'll need to create your `System` user. First you'll need to create your `Decidim::System` user in your production Ruby on Rails console:
 
 ```ruby
@@ -103,7 +102,7 @@ If you want, you can create seed data in production. Run this command in your pr
 $ SEED=true rails db:seed
 ```
 
-If you used Codegram's [`decidim-deploy-heroku`](https://github.com/codegram/decidim-deploy-heroku), then you're all set. Otherwise you'll need to login as system user and edit the host for the organization. Set it to you production host, without the protocol and the port (so if your host is `https://my.host:3001`, you need to write `my.host`).
+You'll need to login as system user and edit the host for the organization. Set it to you production host, without the protocol and the port (so if your host is `https://my.host:3001`, you need to write `my.host`).
 
 ## Keeping your app up-to-date
 

data/docs/{how_to_create_a_plugin.md → how_to_create_a_module.md}

@@ -23,7 +23,7 @@
       s.email = ["your_eamail@example.org"]
       s.license = "AGPL-3.0"
       s.homepage = "https://github.com/decidim/decidim"
-      s.required_ruby_version = ">= 2.3.1"
+      s.required_ruby_version = ">= 2.4.2"
 
       s.name = "decidim-<engine_name>"
       s.summary = "<engine_description>"
@@ -156,8 +156,13 @@
     Decidim::Dev.dummy_app_path = File.expand_path(File.join("..", "spec", "decidim_dummy_app"))
 
     require "decidim/dev/test/base_spec_helper"
+
     ```
 
+1. Upload 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).
+
+
 ## Experimental way
 
 Plugin creation is being automated in