decidim 0.23.6 → 0.24.0.rc1

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

@@ -1,36 +1,39 @@
-# How to profile a Decidim app
+= 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:
+The development_app includes a bunch of gems that profile the application. Run the following command in the decidim root's folder:
 
-```bash
+[source,bash]
+----
 bundle exec rake development_app
-```
+----
 
 and then move into it and boot the server
 
-```bash
-cd developmen_app
+[source,bash]
+----
+cd development_app
 bundle exec rails s
-```
+----
 
-## Bullet
+== 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
+[source,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
+== 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.
 
@@ -38,6 +41,6 @@ This gem is further enhanced with the `flamegraph`, `stackprof` and `memory_prof
 
 More details: https://github.com/MiniProfiler/rack-mini-profiler
 
-## Profiling best practices
+== 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/modules/develop/pages/releases.adoc

@@ -0,0 +1,148 @@
+= 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` to find out the owners of the gem. It's worth making sure you're owner of all gems.
+
+Remember to follow the Gitflow branching workflow.
+
+== Create the stable branch for the release
+
+. Go to develop with `git checkout develop`
+. Create the release branch `git checkout -b release/x.y-stable && git push origin release/x.y-stable`.
+. 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:
+
+. Go back to develop with `git checkout develop`
+. Turn develop into the `dev` branch for the next release:
+ .. 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
+ .. Run `bin/rake update_versions`, this will update all references to the new version.
+ .. Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
+ .. Run `bin/rake webpack`, this will update the JavaScript bundle.
+. Update `SECURITY.md` and change the supported version to the new version.
+. 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.
+
+[source,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.
+----
+
+. Push the changes `git add . && git commit -m "Bump develop to next release version" && git push origin develop`
+
+== Producing the CHANGELOG.md
+
+Look for the "Bump develop to next release version" commit sha1.
+You can do it either visually with `gitk .decidim-version` or by blaming `git blame .decidim-version`.
+
+Here you have different options to see what happened from one revision to another:
+
+[source,bash]
+----
+git log v0.20.0..v0.20.1 --grep " (#[0-9]\+)" --oneline
+git log <SHA>..HEAD --grep " (#[0-9]\+)" --oneline
+----
+
+Once you've checked the list of changes, it's time to actually generating the changelog.
+
+[source,bash]
+----
+bin/changelog_generator
+----
+
+Running it as is, or passing it the `--help` flag, will render the help section for the script. In order to actually run the script, follow the instructions:
+
+[source,bash]
+----
+bin/changelog_generator <GITHUB_TOKEN> <SHA>
+----
+
+If you have some elements in the `Unsorted` section of the output, you can review the PRs individually, fix the title and the tags and rerun the script. Those PRs with the tags fixed will be automatically sorted. Labelling the PRs as they're opened or merged is encouraged to save some time when producing the changelog.
+
+You can copy-paste the output of the command to the relevant sections of the changelog file.
+
+== 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:
+
+. Checkout the release stable branch `git checkout release/x.y-stable`.
+. Update `.decidim-version` to the new version `x.y.z.rc1`
+. Run `bin/rake update_versions`, this will update all references to the new version.
+. Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
+. Run `bin/rake webpack`, this will update the JavaScript bundle.
+. Commit all the changes: `git add . && git commit -m "Bump to rcXX version" && git push origin release/x.y-stable`.
+. Tag the release candidate with `git tag vX.Y.Z.rcN && git push origin vX.Y.Z.rcN`.
+
+Usually, at this point, the release branch is deployed to Metadecidim during, at least, one week to validate the stability of the version.
+
+=== During the validation period
+
+. During the validation period, bugfixes must be implemented directly to the current `release/x.y.z-stable` branch and ported to `develop`.
+. 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 Metadecidim) during some period of time (a week at least). When they are considered ready, it is time for them to be released:
+
+. Checkout the release stable branch `git checkout release/x.y-stable`.
+. Update `.decidim-version` by removing the `.rcN` suffix, leaving a clean version number like `x.y.z`
+. Run `bin/rake update_versions`, this will update all references to the new version.
+. Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
+. Run `bin/rake webpack`, this will update the JavaScript bundle.
+. 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.
+. Commit all the changes: `git add . && git commit -m "Bump to v0.XX.0 final version" && git push origin release/x.y-stable`.
+. Run `git pull && bin/rake release_all`, this will create all the tags, push the commits and tags and release the gems to RubyGems.
+. Once all the gems are published you should create a new release at this repository, just go to the https://github.com/decidim/decidim/releases[releases page] and create a new one.
+. Update Decidim's Docker repository as explained in the Docker images section below.
+. Update Crowdin synchronization configuration with Github:
+ .. Add the new `release/x.y-stable` branch.
+ .. Remove from Crowdin branches that are not officially supported anymore.
+That way they don't synchronize with Github.
+. 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:
+
+. Checkout the branch you want to release: `git checkout -b release/x.y-stable`
+. Update `.decidim-version` to the new version number.
+. Run `bin/rake update_versions`, this will update all references to the new version.
+. Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
+. Run `bin/rake webpack`, this will update the JavaScript bundle.
+. 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.
+. Commit all the changes: `git add . && git commit -m "Prepare VERSION release"`
+. Run `bin/rake release_all`, this will create all the tags, push the commits and tags and release the gems to RubyGems.
+. Once all the gems are published you should create a new release at this repository, just go to the https://github.com/decidim/decidim/releases[releases page] and create a new one.
+. Update Decidim's Docker repository as explained in the Docker images section.
+
+== Docker images for each release
+
+Each release triggers a https://github.com/decidim/decidim/blob/develop/.github/workflows/on_release.yml[GitHub workflow] that rebuilds and publishes the https://github.com/decidim/docker[decidim/docker images] to https://github.com/orgs/decidim/packages[GitHub Container Registry] and https://hub.docker.com/repository/docker/decidim/decidim[Docker Hub].

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

@@ -0,0 +1,31 @@
+= Reportable
+
+== Resources can be reportable
+
+`Reportable` is a feature that allows Decidim resources to be reported by users.
+A resource can be reported by a user as 'spam', 'offensive' or 'does_not_belong'.
+
+When a resource is reported, a `Report` is created.
+All ``Report``s of a resource are grouped in a `Moderation` and can be moderated by the admins.
+
+A `Reportable` is expected to implement:
+
+* `reported_content_url`: the URL for the reportable resource;
+* `reported_attributes`: a list of attributes that can be reported (e.g.
+`[:title, :body]`) - used to display the report content by the `ReportedContentCell`;
+* `reported_searchable_content_extras` (optional): a list of attributes other than `reported_attributes` the report can be search by (e.g.
+`[author.name]`) - used in the reports search bar of the admin panel.
+
+== Public view
+
+=== The ReportedContentCell
+
+The reccomended way to render the content of a `Reportable` is with a `decidim/reported_content` cell.
+
+[source,ruby]
+----
+cell("decidim/reported_content", reportable)
+----
+
+By default, this will render the generic `Decidim::ReportedContentCell`.
+You can also customize the template for your `Reportable` by extending `Decidim::ReportedContentCell` (see `Decidim::Proposal::ReportedContentCell`)

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

@@ -0,0 +1,33 @@
+= Security Policy
+
+== Supported Versions
+
+Until we have the version 1.0 we support only the last minor and major
+version with security updates.
+
+|===
+| Version | Supported
+
+| 0.21.x
+| :white_check_mark:
+
+| \<= 0.20
+| :x:
+|===
+
+== Reporting a Vulnerability
+
+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.
+
+We recommend to use GPG for these kind of communications, the fingerprint
+is `C1BD 8981 D83C 23F9 D419 FE42 149A D0F9 84B9 35C4`. To download our key:
+
+[source,bash]
+----
+gpg --keyserver pgp.key-server.io --recv 84B935C4
+----

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

@@ -1,53 +1,57 @@
-# Share tokens
+= 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
+== 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
+[source,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
+== 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).
+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
+[source,ruby]
+----
 token = context[:share_token]
 
 return unless token.present?
 
 allow! if Decidim::ShareToken.use!(token_for: your_resource, token: token)
-```
+----
 
-## Manage tokens
+== Manage tokens
 
 Render the partial `decidim-admin/app/views/decidim/admin/share_tokens/_share_tokens.html.erb` inside a view, with:
 
-```ruby
+[source,ruby]
+----
 locals: { share_tokens: your_share_tokens_variable }
-```
+----
 
 to let admins see and manage tokens for that resource.
 
-## Link to url with token
+== 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
+[source,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
-```
+----

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

@@ -1,24 +1,25 @@
-# Templates
+= Templates
 
 Templates can be defined from their own section in the admin panel to store and use objects with given values and use them to create new ones using these values as default.
 
-## Model
+== Model
 
 The only requisite to create a template for a model is that the model class includes the `Decidim::Templates::Templatable` concern.
 
-## Controller
+== Controller
 
 A controller must be created in `decidim-templates/app/controllers/decidim/templates/admin` for the template management actions: `index`, `new`, `create`, `edit`, `update`, `delete` and the additional `copy`, `apply`, `skip` and `preview` actions.
 
-## Commands
+== Commands
 
 You should create at least the custom `create`, `copy` and `apply` commands for the model templates in `decidim-templates/app/commands/decidim/templates/admin`, and can use the general `destroy` and `update` commands in the controller, which need to be called only with the `Template` itself.
 
-## Routes
+== Routes
 
 The following routes should be defined in `decidim-templates/lib/decidim/templates/admin_engine.rb`.
 
-```ruby
+[source,ruby]
+----
 resources :$MODEL_templates do
   member do
     post :copy
@@ -32,25 +33,26 @@ resources :$MODEL_templates do
     get :preview # To provide a preview for the template in the object creation view
   end
 end
-```
+----
 
-## Views
+== Views
 
 All views related to a model's template management must be created inside `decidim-templates/app/views/decidim/templates/admin/$MODEL_templates`.
 
-## Testing
+== Testing
 
 The factory for a specific model's template should be defined in `decidim-templates/lib/decidim/templates/test/factories.rb`, inside the general `:template` factory.
 
-## Other
+== Other
 
 Add the route to the model templates index inside `decidim-templates/app/controllers/decidim/templates/admin/application_controller.rb`, providing the title and the index root.
 
-```ruby
+[source,ruby]
+----
 def template_types
   @template_types ||= {
     I18n.t("template_types.questionnaires", scope: "decidim.templates") => decidim_admin_templates.questionnaire_templates_path,
     I18n.t("template_types.$MODEL_PLURAL", scope: "decidim.templates") => decidim_admin_templates.$MODEL_templates_path,
   }
 end
-```
+----

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

@@ -1,48 +1,49 @@
-# How to test Decidim engines
+= How to test Decidim engines
 
-## Requirements
+== Requirements
 
 You need to create a dummy application to run your tests. Run the following command in the decidim root's folder:
 
-```bash
+[source,bash]
+----
 bundle exec rake test_app
-```
+----
 
-## Running a specific test file or just a single spec
+== Running a specific test file or just a single spec
 
-If you are writing new specs, you can run the tests contained in a single file by opening a console window in the corresponding module and calling `rspec`on the file. For example:
+If you are writing new specs, you can run the tests contained in a single file by opening a console window in the corresponding module and calling ``rspec``on the file. For example:
 
-```bash
+[source,bash]
+----
 cd decidim-participatory_processes
 bundle exec rspec spec/forms/participatory_process_form_spec.rb
-```
+----
 
 You can also run a single test by appending its start line number to the command:
 
-```bash
+[source,bash]
+----
 bundle exec rspec spec/forms/participatory_process_form_spec.rb:134
-```
+----
 
-## Running tests for a specific component
+== Running tests for a specific component
 
 A Decidim engine can be tested running the rake task named after it. For
 example, to test the proposals engine, you can run:
 
-```bash
+[source,bash]
+----
 bundle exec rake test_proposals
-```
+----
 
-## Running the whole test suite
+== Running the whole test suite
 
 You can also run the full thing including test application generation and tests
 for all components by running
 
-```bash
+[source,bash]
+----
 bundle exec rake test_all
-```
+----
 
 But beware, it takes a long time... :)
-
-## Make CircleCI not run tests for a specific commit
-
-If you want that CircleCI no run tests for a specific commit, add this in your commit message `[ci_skip]`