decidim / decidim

The participatory democracy framework. A generator and multiple gems made with Ruby on Rails

The participatory democracy framework

Free Open-Source participatory democracy, citizen participation and open government for cities and organizations.
Explore the docs »

Join our Matrix.org chat rooms.

Features · Roadmap · Report Bug · Propose New Features · Read Blog

💡 What is Decidim?

Decidim is a participatory democracy framework, written in Ruby on Rails, originally developed for the Barcelona City government online and offline participation website. Installing these libraries will provide you a generator and gems to help you develop web applications like the ones found on example applications or like our demo application.

All members of the Decidim community agree with Decidim Social Contract or Code of Democratic Guarantees.

---

Table of Contents

• 🚀 Getting started

• 🙌 Contribute

• 🧩 Modules

  • 🪪 Identity verifications and authorizations

  • 🚪 Authentication options

• 📘 License

• 🔎 Example applications

• 🔒 Security

• 🫶 Financial contributions

  • 🧑 Members

  • 💻 Partners

• 📖 Learn More

• 🎩 Credits

---

🚀 Getting started

TLDR: install gem, generate a Ruby on Rails app, enjoy.

gem install decidim
decidim decidim_application

We have set up a guide on how to install, set up and upgrade Decidim. See the Getting started guide.

🙌 Contribute

Anyone can participate in Metadecidim, our own distance of Decidim for improving Decidim. The community is formed by people with different profiles and backgrounds.

How can you contribute? There are many ways to do it, some more specific to the software -improving documentation or translations, reporting bugs or proposing improvements-, but you can also participate in discussions about the governance of the community (find out how we organize ourselves).

Having a lively community is crucial to this project, so we encourage you to find out what is the best way for you to contribute to the commons! 🌱

Read more about contributions in our contribution guidelines.

🧩 Modules

If you need to have some features that we do not have yet, we recommend that you make a module. This is a Ruby on Rails engine with some APIs specific to Decidim (for registering with the menus, integration with spaces like Participatory Processes or Assemblies, with /admin or /api, etc).

As a base you can use these modules, although check first that the version is compatible with your current Decidim version. Also, you should know that until v1.0.0 we are under development, and these internal APIs can change.

We recommend that you extensively test your module.

See Modules page on Decidim.org.

🪪 Identity verifications and authorizations

One specific thing regarding these kind of applications is how you manage the permissions that the participants will have in the platform (aka the authorization or verification logic). This tries to solve the problem of how to verify that the user is who they say they are and that they have the right to participate in this city or organization. Read more about Authorizations in our documentation.

🚪 Authentication options

You can easily add any authentication provider to Decidim that is provided by OmniAuth. Also you have a list of modules related to authorization already developed by the community.

📘 License

If you plan to put your application in production, you will need to publish it using the same license: GPL Affero 3.

We recommend doing that on GitHub (or any other code hosting platform) before publishing.

You can read more on "Being Open Source From Day One is Especially Important for Government Projects".

If you have any trouble you can contact us on our Matrix.org chat room for developers.

🔎 Example applications

Since Decidim is a ruby gem, you can check out the dependent repositories to see how many applications are on the wild or tests that other developers have made. You can see a highlight of example applications in our documentation.

🔒 Security

Security is very important to us. If you have any issue regarding security, please disclose the information responsibly by sending an email to security [at] decidim [dot] org and not by creating a github/metadecidim issue. We appreciate your effort to make Decidim more secure. See full security policy.

🫶 Financial contributions

Decidim helps citizens, organizations and public institutions to democratically self-organize at every scale. Thanks to Decidim, any organization is able to configure spaces for participation (initiatives, assemblies, or processes) and enrich them through the multiple available components (meetings, surveys, proposals, participatory budgets, accountability for results, comments, and many other).

You can contribute financially to the sustainability of this project through OpenCollective.

The funds will enable the maintainers to:

• review community contributions

• triage issues

• fix bugs related to performance

• improve the design of the platform

• write better documentation

• improve performance of the platform security

🧑 Members

Members have the right to participate in all the participation spaces of the Metadecidim platform with voice and vote, exercise their vote in strategic and internal decisions, elect or be elected in representative bodies, request and obtain explanations about the management of the positions of the Association, receive information about the activities and make common uses that are established. Read more about becoming a Decidim association member.

💻 Partners

Any organization offering services on Decidim can contribute back to the commons by becoming a Partner. Each Partner commits to include a clause in each new service contract around Decidim, explicitly stating that a small percentage is allocated to the maintenance of the source code. For a company, the percentage is 3%, and for a nonprofit organization, it is 1.5%. Read more about becoming a Decidim association partner.

📖 Learn More

Decidim Resource	Description
🚀 Our latest releases	New features and bug fixes.
🧩 Modules	Find out new ways of enhancing Decidim.
🗳 Propose new Features	Is there any missing feature? Propose a new one!
📓 Docs	Full documentation for creating and customizing your own Decidim application.
📒 API Reference	Detailed reference on Decidim’s API.
🔎 Examples	See some ways where Decidim is used, with code examples.
📬 Blog	All the latest news and releases from Decidim.
💬 Join Matrix.org	Need help with your specific use case? Say hi on Matrix!
🗺 Roadmap	See where Decidim is working to build new features.
🙌 Contribute	How to contribute to the Decidim project and code base.

🎩 Credits

• This project is tested with BrowserStack.

decidim's Issues

System panel

• System users
• Organizations (with paranoid deletion)

Consider using/defining Content Security Policy

What

https://developers.google.com/web/fundamentals/security/csp/

Why

https://github.com/blog/1477-content-security-policy

How

https://github.com/twitter/secureheaders
https://blog.sqreen.io/integrating-content-security-policy-into-your-rails-applications-4f883eed8f45/

Fix TranslatableAttributes to accept locales with a dash

We should fix TranslatableAttribute so it works with locales with a dash like zn-CH.

Add Processes' public page

Depends on #53

Processes should be shown as specified in decidim-design.

They should have:

• An index page listing all the processes.
• A show page showing an overview of the process. We can skip the steps by now.

Test ticket from Code Climate

Store locale in users

By storing locales inside the users table, we can handle a couple scenarios when we loose context:

• Async tasks that run without the user's interaction (weekly newsletters)
• Setting a locale when the user logs in

Move test support to a separate gem `decidim-testing`

This would allow us specifying that gem as a development dependency, thus avoiding polluting the consumer's namespace with unnecessary generators and stuff.

Localize emails depending on the receiver's locale

E-mails should be localized depending on the user's locale (stored in the user's table). I've achieved this in the past by implementing a with_user_locale(user, &block) helper:

with_user_locale(user) do
  # Render email
end

User registration

Add user registration following decidim-design's design.

• When a user registers, it receives a confirmation e-mail. Signing in for that user is blocked until confirmed.
• There's no residence authentication yet.

Participatory processes shouldn't be published by default

We should add a field to processes so that they aren't published by default until an admin decided to do so. Unpublished processes aren't shown at the public pages and can't be accessed by regular users (admin could access them from a link in the admin dashboard).

I'd do it with a published_at datetime field that default to nil.

Add session box

Depends on #40 and #43. Implement the session box feature, including the dropdown panel and the responsive menu.

Users should be able to:

• Register and sign in when not signed in
• Log out when signed in

Sending emails

Tasks needed in order for decidim to send emails.

Add I18n support to Participatory Processes fields

In order to fully support I18n on participatory processes, we should add I18n to its fields & views.

Add Docker build step in Circle CI

Add a CircleCI step to build decidim docker base image.

Add an authorization system (pundit, cancancan?) and remove all previous ad-hoc authorization logic.

• User
• CurrentOrganization

Add Processes' steps

Depends on #53

A Process contains several steps. Every Step will, eventually, have a set of features associated. By now though, we'll only be adding steps as a way to display information about the timeline of a Process.

A Step has:

• Title (I18n, required)
• Short description (I18n, required)
• Long description (I18n, required)
• Start date (optional)
• End date (optional)
• An association with a ParticipatoryProcess
• A position within the ParticipatoryProcess

Positions of a step within a ParticipatoryProcess could be deducted from start dates, but unfortunately it's quite common that we don't have that information when starting a process.

A ParticipatoryProcess can only have a single active Step. We can do it via an active flag in the Step or an active_step association within the ParticipatoryProcess. That's up to the implementer.

How to QA?

• Steps of a Participatory Process can be created, modified, deleted and resorted within the admin panel
• Steps are shown as a timeline in the Process page.

Fix missing `ca.time.formats.short`

Some locales seem to be missing time formats, like the Catalan one. In a recent deployment, I had ActionView::Template::Error (translation missing: ca.time.formats.short) in Decidim::System::OrganizationsController#index as HTML.

Add process administrators

🎩 User Story

In order to give more granularity to process administration, we'll define a process administrator persona that has to be given express permission to manage a subset of participatory process.

A process admin can:

• List all of her participatory processes
• See a particular participatory process even if it's unpublished
• Manage everything related to that participatory process (steps)
• Give other users permission to a participatory process

Of course, admins can also do all of that.

📋 Related documentation

None

🎯 Acceptance criteria

Process administrators can be defined for a process. Process managers can log in to the admin panel and see/manage only their assigned processes.

📌 Related issues

None

Add deployment helpers to the generators

When generating a new app, we should provide a set of deployment facilities. These could include:

• An Dockerfile and docker-compose.yml
• A Heroku's app.json with a predefined Heroku button

Implement basic organization layout

By using decidim-design as a reference, we should be able to implement a basic layout for an organization's public page. It shouldn't include any advanced features as the session box, but it should show a nice landing page with the organization's title.

A few notes:

• decidim-design uses middleman so some of its helpers will just work in rails. I've also added an icon helper ad decidim-design that should be reimplemented in terms of Rails' asset pipeline and asset locations.
• Don't rewrite or modify any CSS from decidim-design when importing it, as it will probably change. If you have to override something, just do it in a separate scss file.

Participatory processes attachments

A process could have many file attachments related to it and they should be shown at the public page.

We need an admin section to manage these attachments.

They should look like this:

An attachment should have these properties:

• Title (translated)
• Description (translated), and maybe limited to 255 chars.
• File
• FileType
• Size

Create a decidim-engine generator

So we can generate new engines with our custom format.

Fix auto-deployment

Our custom staging deployment system is malfunctioning when we trigger the build and there's another build on the way.

We can mitigate this by either:

• Adding a naive queueing system that prevents two simultaneous builds.
• Canceling the previous build when a new build arrives.

Create a WYSIWYG editor field

🎩 User Story

In order to have rich text fields in our forms, we should add a WYSIWYG editor.

WYSIWYG should be configurable at the view level:

• Basic (default): p, strong, em, lists and links.
• Full: All the above plus headers.

📋 Related documentation

Quill.js seems right for the job.

• http://quilljs.com/

🎯 Acceptance criteria

Rich text editors should show on:

• Process
  • Description
  • Short description
• Pages (depends on #190)
  • Content
• Steps
  • Description
  • Short description

DroneCI builds can't connect to PostgreSQL

The latest DroneCI builds seem to be failing dues to Drone being unable to connect to PostgreSQL: http://ci.decidim.codegram.com/codegram/decidim/23

Add registration and sign in design & layout

Reference:

• http://decidim-design.marsbased.com/user-register/
• http://decidim-design.marsbased.com/user-login/

Note: We don't have nither the organization nor the oauth functionality, so let's skip that.

Add project-wide configuration

• E-mail should probably be send from a single, installation-wide address that should be configured at decidim.rb's initializer.
• Expose carrierwave's configuration (either using Decidim.setup or exposing an initializer)
• Ideas?

Add locale switcher

Each UI should implement a locale switcher.

You can use decidim-design for the main organization UI, and use that an inspiration to implement decidim-system and decidim-admin.

A locale switcher should:

• Keep you in the exact same page after switching.
• Deduce the right locale to use following well-established methods like checking out browser's locale.
• Update the user's locale attribute after switching, in case the user's logged in.
• Change the locale to the user's when logging in.
• Set the user's locale to the UI's locale when registering.

Add email layout

Use decidim-design's email template based on Foundation for Emails.

Please use the roadie gem that automatically appends CSS to the email's DOM.

Framework statistics

I'd be great if we add a feature that collects framework statistics: usage, deployments, etc.

We can get some inspiration from Serverless: https://github.com/serverless/serverless/blob/master/lib/classes/Utils.js

Fix "Similar code" issue in decidim-core/lib/generators/decidim/dummy_generator.rb

Similar code found in 1 other location (mass = 73)

https://codeclimate.com/github/codegram/decidim/decidim-core/lib/generators/decidim/dummy_generator.rb#issue_57e5295be850a2000100008b

UX improvements

All things UX

Make e-mail sending async

We should start adding async worker capabilities. E-mails, above all other things, should be sent asynchronously. This means we should add first-class support to ActiveJob inside decidim.

I have my doubts: Should we hard-code an explicit dependency (sidekiq?) or let the developer choose? Is ActiveJob flexible enough?

Add seeds

We should add two kinds of seeds:

• Development seeds: These seeds should contain example information and will also be used in staging environments as example data. Would be great to have them documented in the README, at least its login information.
• Production seeds: Should contain the bare essentials to run a production environment; probably just a system admin. They should be documented as well.

Note that each engine should contain its own seeds. We can sort of handle this in several ways:

1. Providing a single Decidim.seed method, and have all engines register seeds via a Decidim.register_seed method somewhere
2. We could broadcast a seed signal when the seeds are run and capture them via ActiveSupport::Notifications. That could also be the beginning of a broader-size pub-sub mechanism between engines.
3. We could just run all seeds separately (Decidim::Core.seed, Decidim::System.seed and Decidim::Admin.seed) and put them into seeds.rb via the app generator, but that's sub-optimal and doesn't scale if we end up adding more engines.

I personally prefer 1) or 2) but that's up to the implementer.

Use tabs to deal with multilanguage fields in the admin panel

🎩 User Story

In order to improve the multilanguage fields' usability in the admin panel, we should switch to a tabs-based interface. We're using foundation, which has a tabbed interface built-in.

Note: We have to find a way to show all the errors related to all the languages on a single error field, as having tabs could potentially hide the error from the user.

📋 Related documentation

https://foundation.zurb.com/sites/docs/tabs.html

🎯 Acceptance criteria

All multilanguage fields are shown in tabs instead of a line for each language. The I18n.default language appears first, the rest of them afterwards.

Processes

Epic task related to Processes.

Autogenerate process slug from default locale

Use the default locale to generate the slug for the process. It can be overwritten from the form

Devise's Failure app can't find the right scope

After looking into the issue, I've found out the source of the problem. It turns out that the keys in Devise.mappings are symbols but somehow we're looking for them as strings.

How to reproduce

Navigate to /admin within an organization.

Temporary solution...?

The problem is mitigated by monkey-patching our Decidim::DeviseFailureApp:

def scope
  @scope ||= (warden_options[:scope] || Devise.default_scope).to_sym
end

It doesn't look like the way to go though. We should look further into it.

Organization admin welcome

In order to manage a particular organization, we need to provide an admin that will act as a home for all the administration endeavours.

Add Processes' admin panel

Interaction within a user and an organization is mainly done via Processes. A Process is a unit of action from the Organization point of view that groups several features (proposals, debates...) distributed in steps that get enabled or disabled depending on which step is currently active.

We're not implementing that logic yet. By now, we only need the organization's admin panel to allow certain users (depending on a role) to create participatory processes. A participatory process has:

• An I18n title
• A slug
• A hashtag (optional)
• An I18n subtitle
• An I18n short description
• An I18n description
• A set of images, each one with different formats (banner, hero...)

Organization's layout

Implement the organization's public layout. This is actually an epic comprised by several issues.

Move app generators to the `decidim` gem (instead of `decidim-core`).

I believe the generators should live in the decidim gem, which groups all the other gems considered "essential" and acts as a bridge between them.

The decidim gem defines the happy path for a standard installation and should provide the facilities to do so. Each gem included in the bundle should live (reasonably) without knowledge of each other's existence.

Add style linters to the `install` generator

It'd be really useful to provide a set of linter configurations to the generated projects as .rubocop.yml, csslint, etc.

Generate decidim application using decidim specific gem branch

We can add a --branch flag to generate a decidim application to use a specific branch of decidim gem.

Example:

bin/decidim --branch docker new_app

generates a Gemfile like this:

gem 'decidim', github: 'codegram/decidim', branch: 'docker'

Error pages

We need to implement the design for the error pages:

• 404: http://decidim-design.marsbased.com/404/
• 500: http://decidim-design.marsbased.com/500/

Add html_truncate gem

Revert the commit codegram@d5c2017 and replace it by https://github.com/nono/HTML-Truncator

Participatory process attachments

🎩 User Story

Participatory processes and steps can have arbitrary attachments that will then be shown on their public pages.

We need an admin section to manage these attachments.

These attachments can be:

• Images: They will generate a processed thumbnail version and shown in the image gallery.
• Documents & other types: If the type is not known, it will be shown in the documents section.

An attachment should have these properties:

• Title (translated)
• Description (translated), and maybe limited to 255 chars.
• File
• FileType
• Size

Notes

As we're going to have attachments in many other resources, we could create a polymorphic relationship between an Attachment and the resource.

📋 Related documentation

Reference: http://decidim-design.marsbased.com/info/

🎯 Acceptance criteria

Attachments of a participatory process can be managed in a participatory process' admin, they're displayed with their name & filetype icon and can be downloaded.

Automate deployments

We should have a staging server with a sample app that gets re-deployed each time new commits are pushed into this repo's master.

User registration

Localization

Epic task related to internationalization.