decidim 0.23.5 → 0.24.2

data/docs/modules/develop/pages/docker.adoc

@@ -0,0 +1,12 @@
+= Decidim on Docker
+
+There's an https://github.com/orgs/decidim/packages/container/package/decidim[image available for a default Decidim app], with core modules. It gets updated with each new version release.
+
+The https://github.com/decidim/docker/blob/master/Dockerfile-deploy[Dockerfile] and https://github.com/decidim/docker/blob/master/docker-compose.yml[a basic docker-compose.yml file] are both available on the https://github.com/decidim/docker[decidim/docker repo], in case you'd like to use them as starting points for your own customized images and deployments.
+
+Note that the usual requirements for Docker and Rails deployments apply here:
+
+. A https://docs.docker.com/storage/[persistent volume] is required for file uploads, logs and any changing, persisted data. Docker images are stateless by design, so they can be easily updated, restarted and replicated.
+. Rails file uploads are handled by https://guides.rubyonrails.org/active_storage_overview.html[Rails' Active Storage]. Their guide will have the ins and outs of configuring file storage on Rails, including delegating it to file storage in the cloud, for example.
+
+For a more elaborate example of docker compose usage, including setting volumes and SSL, among other things, please see https://github.com/AjuntamentDeSabadell/decidim-sabadell/blob/master/docker-compose.yml[the docker-compose.yml for the Decidim instance deployed for the city of Sabadell], in Catalunya.

data/docs/{advanced/embeddable.md → modules/develop/pages/embeddable.adoc}

@@ -1,15 +1,15 @@
-# Embeddable
+= Embeddable
 
 `Decidim` allows you to share a information box related to some spaces as:
 
-- **Assemblies**
-- **Conferences**
-- **Initiatives**
-- **Participatory processes**
+* *Assemblies*
+* *Conferences*
+* *Initiatives*
+* *Participatory processes*
 
 or even `Meetings` component in an easy way with the `embeddable` option that offers the platform.
 
-## How to
+== How to
 
 All that you have to do, is to enter into whathever space/component you want to share info to, and look for down right part of the page to find embeddable share option.
 

data/docs/{advanced/endorsable.md → modules/develop/pages/endorsable.adoc}

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

data/docs/{advanced/fixing_locales.md → modules/develop/pages/fixing_locales.adoc}

@@ -1,68 +1,80 @@
-# Fixing locales
+= Fixing locales
 
 Sometimes in production environments you are force to change the locales available for an organization.
 
 However, this may be delicate, specially if you need to remove them.
 
-## Change the available languages of an organization
+== Change the available languages of an organization
 
-When you create an organization, you choose the available languages for it (through the `/system/` url). However, when trying to edit it, the language selector is not available anymore. Here is a way to update that locales manually:
+When you create an organization, you choose the available languages for it (through the `/system/` url).
+However, when trying to edit it, the language selector is not available anymore.
+Here is a way to update that locales manually:
 
 First, make sure that your initializer file has all the locales you want:
 
 Edit the file `config/initializers/decidim.rb` and be sure to include all the necessary locales:
 
-```ruby
+[source,ruby]
+----
 ...
 # Change these lines to set your preferred locales
   config.default_locale = :en
   config.available_locales = [:en, :ca, :es, :fr, :pt]
 ..
-```
+----
 
 Then you need to access the rails console and update the organization locales manually.
 
-Access to your rails console and select your organization. If you have only one organization you can just run the command:
+Access to your rails console and select your organization.
+If you have only one organization you can just run the command:
 
-```ruby
+[source,ruby]
+----
 o=Decidim::Organization.first
-```
+----
 
 Check your current locales:
 
-```ruby
+[source,ruby]
+----
 o.available_locales
 => ["en", "ca", "es"]
-```
+----
 
 Then add or remove locales and save the organization.
 
-```ruby
+[source,ruby]
+----
 o.available_locales += ["fr", "pt"]
 => ["en", "ca", "es", "pt", "fr"]
 o.save!
-```
+----
 
 If you want to change the default locale:
 
-```ruby
+[source,ruby]
+----
 o.default_locale = "fr"
 o.save!
-```
+----
 
-> If you need to remove locales from an organization read the next section!
+____
+If you need to remove locales from an organization read the next section!
+____
 
-## Fixing errors in locales
+== Fixing errors in locales
 
-In certain cases (ie. when removing locales from an organization) some operations in Decidim may lead to errors 500 in the browser.
+In certain cases (ie.
+when removing locales from an organization) some operations in Decidim may lead to errors 500 in the browser.
 
 In order to solve that you can make use of these rake tasks:
 
-### Synchronize Locales
+=== Synchronize Locales
 
-```bash
+[source,bash]
+----
 bundle exec rake decidim:locales:sync_all
-```
+----
 
 Run this task if you have changed `available_locales` or `default_locale` in `config/initializers/decidim.rb` and you think that some organization have values not supported by the Decidim installation.
 
@@ -73,7 +85,7 @@ Examples:
 
 It is safe to run this task as it respects organizations with less languages than the supported.
 
-### Repair the search index
+=== Repair the search index
 
 In order to provide a global search in Decidim, many content is indexed in a search table, each locale separately.
 This means that, if you remove languages, some content can be orphan as the original resource do not exist anymore.
@@ -81,8 +93,9 @@ This leads to server 500 errors.
 
 To repair the search index you can run the rake task:
 
-```bash
+[source,bash]
+----
 bundle exec rake decidim:locales:rebuild_search
-```
+----
 
 Be aware that this might take a long time as it will remove and recreate the whole search index for all organizations.

data/docs/{advanced/followers.md → modules/develop/pages/followable.adoc}

@@ -1,23 +1,25 @@
-# Followers
+= Followers
 
-## Create followers from comment authors
+== Create followers from comment authors
 
 Run the following script to make all comment authors follow the commented resource:
 
-```ruby
+[source,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
+== Create followers from resource authors
 
 Run the following script to make all resource authors follow the resource:
 
-```ruby
+[source,ruby]
+----
 Decidim.component_manifests.each do |component_manifest|
   component_manifest.resource_manifests.each do |resource_manifest|
     klass = resource_manifest.model_class_name.constantize
@@ -31,5 +33,4 @@ Decidim.component_manifests.each do |component_manifest|
     end
   end
 end; p 1
-```
-
+----

data/docs/modules/develop/pages/guide.adoc

@@ -0,0 +1,16 @@
+= Developing Decidim
+
+* xref:develop:guide_architecture.adoc[Architecture]
+* xref:develop:guide_changelog.adoc[Changelog]
+* xref:develop:guide_commands.adoc[Commands]
+* xref:develop:guide_development_app.adoc[Development App]
+* xref:develop:guide_example_apps.adoc[Example Applications]
+* xref:develop:guide_git_conventions.adoc[Git conventions]
+* xref:develop:guide_github_projects.adoc[GitHub Projects Workflow]
+* xref:develop:guide_semver.adoc[Semantic Versioning]
+
+== Good to know
+
+* There is an application with current designs at: https://decidim-design.herokuapp.com/
+* We follow https://12factor.net/[12factor recommendations]
+* For testing, refer to the xref:develop:testing.adoc[testing] guide.

data/docs/modules/develop/pages/guide_architecture.adoc

@@ -0,0 +1,17 @@
+= Architecture
+
+For better understanding Decidim, here you have some diagrams based in the https://c4model.com[C4 model].
+
+TIP: You can read better these images by doing a right click and selecting "View image"
+
+== System Context diagram
+
+include::./c4_context.adoc[]
+
+== Container diagram
+
+include::./c4_container.adoc[]
+
+== Component diagram
+
+include::./c4_component.adoc[]

data/docs/modules/develop/pages/guide_changelog.adoc

@@ -0,0 +1,8 @@
+= Changelog
+
+For keeping track of changes we like the rules of https://keepachangelog.com/en/1.0.0/[Keep A Changelog].
+
+In the past we kept a file for all the development of a given version but that was difficult to maintain, as we had conflicts all the time. See the full discussion in https://github.com/decidim/decidim/issues/5908[#5908]. We decided that:
+
+* We will not ask CHANGELOG for all the changes make on this repository. We will ask for CHANGELOG instructions only for special changes that really need some actions on part of developers/implementers or something to comunicate on the releases notes
+* The CHANGELOG will be manually made as part of the release process with the tooling from git (`git log v0.20.0..v0.20.1 --grep " (#[0-9]\+)" --oneline`) or https://github.com/decidim/decidim/compare/v0.20.0...v0.20.1[github]

data/docs/modules/develop/pages/guide_commands.adoc

@@ -0,0 +1,86 @@
+= Commands
+
+Here are some useful commands and tools for working in this project:
+
+== erb-lint
+
+We use erblint gem to ensure homogeneous formatting of erb files.
+
+[source,console]
+----
+bundle exec erblint --lint-all --autocorrect
+# shortest
+bundle exec erblint --lint-all -a
+# even shortest
+bundle exec erblint -la -a
+----
+
+== I18n
+
+We use i18n-tasks gem to keep translations ordered and without missing/unused keys.
+
+To fix the order of the keys, run:
+
+[source,console]
+----
+# from the root of the project
+bundle exec i18n-tasks normalize --locales en
+----
+
+To list unused i18n keys, run:
+
+[source,console]
+----
+bundle exec  i18n-tasks unused --locales en
+----
+
+== JavaScript linter
+
+https://eslint.org/docs/user-guide/command-line-interface[eslint] and https://palantir.github.io/tslint/[tslint] are used to ensure homogeneous formatting of JavaScript code.
+
+To lint and try to fix linting errors, run:
+
+[source,console]
+----
+npm run lint --fix
+----
+
+== Stylelinter
+
+https://stylelint.io/[stylelint] is a CSS linter and fixer that helps to avoid errors and enforce consistent conventions in the stylesheets. Is an npm package, install it using:
+
+[source,console]
+----
+npm install -g stylelint
+----
+
+Linting a `.scss` file:
+
+[source,console]
+----
+stylelint [path-to-file]
+----
+
+With `--fix` option https://stylelint.io/user-guide/cli/#autofixing-errors[stylelint] will fix as many errors as possible. The fixes are made to the actual source files. All unfixed errors will be reported.
+
+[source,console]
+----
+stylelint [path-to-file] --fix
+----
+
+== Rubocop
+
+RuboCop is a code analyzer tool we use at Decidim to enforce our code formatting guidelines.
+
+[source,console]
+----
+# Run Rubocop
+bundle exec rubocop
+# Run Rubocop and automatically correct offenses
+bundle exec rubocop -a
+----
+
+== Markdown linter
+
+This project uses https://github.com/markdownlint/markdownlint[markdownlint] to check markdown files and flag style issues.
+