decidim 0.22.0 → 0.23.0

data/docs/development_guide.md

@@ -30,9 +30,9 @@ Once created you are ready to:
 
 - `bin/rails s`
 
-## Gitflow Branching model
+## GitFlow Branching model
 
-The Decidim respository follows the Gitflow branching model. There are good documentations on it at:
+The Decidim respository follows the GitFlow branching model. There are good documentations on it at:
 
 - the original post: https://nvie.com/posts/a-successful-git-branching-model/
 - provided by Atlassian: https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow.
@@ -43,24 +43,41 @@ In summary, Decidim developers that work on `feature/...` or `fix/...` branches
 
 Then, to start a new feature branch off from `develop` in the following way:
 
-```
+```bash
 git checkout develop
 git checkout -b feature/xxx
 ```
 
 Implement the feature, and open a Pull Request as normal, but against `develop` branch. As this is the most common operation, `develop` is the default branch instead of `master`.
 
+### Naming Decidim branches
+
+We would like to have all branches following this namings:
+
+| Branch prefix | Comment |
+| --------  | -------- |
+| chore/    | Internal work. For instance, automatisms, etc. No production code change.     |
+| ci/       | For continous integration related tasks. No production code change.     |
+| deps/     | For dependency management tasks. |
+| doc/      | For changes to the documentation. |
+| feature/  | For new features for the users or for the Decidim command.  |
+| fix/      | For feature bugfixing. |
+| release/  | With MAYOR.MINOR-stable. For instance, release/0.22-stable |
+| refactor/ | For refactorings related with production code. |
+| test/     | When adding missing tests, refactoring tests, improving coverage, etc. |
+| backport/ | We only offer support for the last mayor version.  |
+
 ## Git commit messages and Pull Request titles
 
 We recommend following [this guide](https://chris.beams.io/posts/git-commit/) for making good git commit messages. It also applies to Pull Request titles. The summary is:
 
-1.  Separate subject from body with a blank line
-1.  Limit the subject line to 50 characters
-1.  Capitalize the subject line
-1.  Do not end the subject line with a period
-1.  Use the imperative mood in the subject line
-1.  Wrap the body at 72 characters
-1.  Use the body to explain what and why vs. how
+1. Separate subject from body with a blank line
+1. Limit the subject line to 50 characters
+1. Capitalize the subject line
+1. Do not end the subject line with a period
+1. Use the imperative mood in the subject line
+1. Wrap the body at 72 characters
+1. Use the body to explain what and why vs. how
 
 ## During development
 

data/docs/getting_started.md

@@ -167,9 +167,11 @@ You can also make sure new translations are complete for all languages in your
 application with:
 
 ```console
-bin/rails decidim:check_locales
+TARGET_BRANCH=release/0.22-stable bin/rails decidim:check_locales
 ```
 
+Here the `TARGET_BRANCH` must be the same as the `decidim` dependency in your `Gemfile`.
+
 Be aware that this task might not be able to detect everything, so make sure you
 also manually check your application before upgrading.
 

data/docs/services/elections_bulletin_board.md

@@ -0,0 +1,38 @@
+# Elections Bulletin Board
+
+:warning: This is a work in progress and is not fully working yet.
+
+In order to celebrate [End-to-end auditable votings](https://en.wikipedia.org/wiki/End-to-end_auditable_voting_systems) using the Elections module, you will need to connect your Decidim instance with an instance of the [Decidim Bulletin Board application](https://github.com/decidim/decidim-bulletin-board/), preferably run by an independent organization.
+
+## Identification pair of keys generation
+
+The first step needed to setup the connection is to generate an a pair of keys to identify the application against the Bulletin Board. This can be done running the following rake task in your application environment:
+
+```sh
+bundle exec rake decidim_elections:generate_identification_keys
+```
+
+This task will output the generated private and public keys. You should copy the public key and send it to the Bulletin Board administrator through a secure channel. When copying the key, include the starting and ending lines with the prefix `-----`.
+
+After that, use one of these methods to make the private key available from your Decidim installation:
+
+a. Copy the private key, paste in a new file and store its path on the environment variable `BULLETIN_BOARD_IDENTIFICATION_PRIVATE_KEY`.
+b. Copy the private key and store that value on the environment variable `BULLETIN_BOARD_IDENTIFICATION_PRIVATE_KEY`.
+
+Regardless of the used method, when copying the private key remember to include the lines prefixed by `-----` and ensure that the private key is not lost between deployments and servers reboots and that only can be accessed by the application.
+
+## Configuration of the Bulletin Board application
+
+The Bulletin Board administrator will store the received public key in their server and will send you back an API key. To complete the setup process you should store this API key and the Bulletin Board URL address on the environment variables `BULLETIN_BOARD_API_KEY` and `BULLETIN_BOARD_SERVER`, respectively.
+
+The following YAML snippet with all the defined environment variables should be used in the `default` block of your application `config/secrets.yml` file. Maybe this is already done, as it was included in the Decidim applications generator during the development of the Elections module.
+
+```yaml
+  bulletin_board:
+    identification_private_key: |
+<%= ENV["BULLETIN_BOARD_IDENTIFICATION_PRIVATE_KEY"]&.indent(6) %>
+    server: <%= ENV["BULLETIN_BOARD_SERVER"] %>
+    api_key: <%= ENV["BULLETIN_BOARD_API_KEY"] %>
+```
+
+After restarting the Decidim instance, administrator users will be able to create elections on the configured Bulletin Board.

data/docs/services/maps.md

@@ -0,0 +1,362 @@
+# Maps and geocoding
+
+Decidim has the ability to geocode proposals and meetings and display them on a
+map. Decidim has built-in support for the following map service providers:
+
+- [HERE Maps][link-here] (Recommended)
+  - Supports map tiles, static map images, geocoding and geocoding
+    autocompletion
+  - Easy to get started with, comes with a rather generous free plan
+  - [Configuring HERE Maps][anchor-configure-here-maps]
+- [Open Street Maps based services][link-osm-commercial]
+  - Please pick a service provider that provides all needed services (map tiles,
+    static map images, geocoding and geocoding autocompletion)
+  - We can't use the OSM's own services by their
+    [tile usage policy][link-osm-tile-usage].
+  - In case your service provider does not offer static map images, Decidim will
+    use the dynamic map tiles to generate a similar map element.
+  - As an alternative, you may also want to use your own self-hosted map servers
+    (see [Hosting your own map services][anchor-hosting-osm] for
+    more information)
+  - [Configuring Open Street Maps based service providers][anchor-configure-osm]
+
+If you want to integrate Decidim to some other map service provider, read how to
+[write your own integration code][link-docs-custom-maps] for that.
+
+## Configuring maps and geocoding
+
+After generating your app, you'll see that your `config/initializers/decidim.rb`
+file includes commented code about map services:
+
+```ruby
+# Map and Geocoder configuration
+# config.maps = {
+#   ...
+# }
+```
+
+The initializer comments provide examples for the services mentioned in this
+documentation. Please refer to the section below for the service you have
+registered for the maps functionality.
+
+If you want to enable geocoding in your app:
+
+1. Select a service provider for the maps functionality and register an account
+   with that provider
+1. Uncomment or add the code under the selected service provider in your
+   `config/initializers/decidim.rb`.
+1. Make sure your `config/secrets.yml` file has the needed section (it should
+   be added by the generator automatically).
+1. Configure the service provider credentials in `config/secrets.yml` and refer
+   to them from your `config/initializers/decidim.rb`.
+1. If you had your Rails server running, restart it so the changes apply.
+
+### Configuring HERE Maps
+
+Use the following configuration for HERE Maps:
+
+`config/initializers/decidim.rb`:
+
+```ruby
+# Map and Geocoder configuration
+# == HERE Maps ==
+config.maps = {
+  provider: :here,
+  api_key: Rails.application.secrets.maps[:api_key],
+  static: { url: "https://image.maps.ls.hereapi.com/mia/1.6/mapview" }
+}
+```
+
+`config/secrets.yml`:
+
+```yaml
+default: &default
+  # ...
+  maps:
+    api_key: <%= ENV["MAPS_API_KEY"] %>
+```
+
+`.env`:
+
+```bash
+MAPS_API_KEY=your_api_key_here
+```
+
+### Configuring Open Street Maps based service providers
+
+Use the following configuration for Open Street Maps based service providers:
+
+`config/initializers/decidim.rb`:
+
+```ruby
+# Map and Geocoder configuration
+# == OpenStreetMap (OSM) services ==
+config.maps = {
+  provider: :osm,
+  api_key: Rails.application.secrets.maps[:api_key],
+  dynamic: {
+    tile_layer: {
+      url: "https://tiles.example.org/{z}/{x}/{y}.png?key={apiKey}",
+      api_key: true,
+      attribution: %(
+        <a href="https://www.openstreetmap.org/copyright" target="_blank">&copy; OpenStreetMap</a> contributors
+      ).strip
+      # Translatable attribution:
+      # attribution: -> { I18n.t("tile_layer_attribution") }
+    }
+  },
+  # static: { url: "https://staticmap.example.org/" }, # optional
+  geocoding: { host: "nominatim.example.org", use_https: true },
+  autocomplete: { url: "https://photon.example.org/api/" }
+}
+```
+
+`config/secrets.yml`:
+
+```yaml
+default: &default
+  # ...
+  maps:
+    api_key: <%= ENV["MAPS_API_KEY"] %>
+```
+
+`.env`:
+
+```bash
+MAPS_API_KEY=your_api_key_here
+```
+
+For further information, see the service provider's documentation or take a look
+at the [Hosting your own map services][anchor-hosting-osm] section.
+
+### Combining multiple service providers
+
+It is also possible to combine multiple service providers for the different
+categories of map services. For instance, if you want to use HERE Maps for
+the map tiles but host the other services yourself, use the following
+configuration:
+
+```ruby
+# Map and Geocoder configuration
+# == Combination (OpenStreetMap default + HERE Maps dynamic map tiles) ==
+config.maps = {
+  provider: :osm,
+  dynamic: {
+    provider: :here,
+    api_key: Rails.application.secrets.maps[:here_api_key]
+  },
+  static: { url: "https://staticmap.example.org/" },
+  geocoding: { host: "nominatim.example.org", use_https: true },
+  autocomplete: { url: "https://photon.example.org/api/" }
+}
+```
+
+`config/secrets.yml`:
+
+```yaml
+default: &default
+  # ...
+  maps:
+    here_api_key: <%= ENV["MAPS_HERE_API_KEY"] %>
+```
+
+`.env`:
+
+```bash
+MAPS_HERE_API_KEY=your_api_key_here
+```
+
+### Disabling some of the map services
+
+When using the maps functionality, you should always aim to provide all the
+services for the user that are available in Decidim. However, not all service
+providers provide all these services, so at times you may need to disable some
+of them.
+
+The configuration syntax allows you to disable the map services one by one. For
+example, if you want to use HERE Maps as your default but disable the static map
+images and geocoding autocompletion functionality, you can use the following
+configuration:
+
+```ruby
+config.maps = {
+  provider: :here,
+  api_key: Rails.application.secrets.maps[:api_key],
+  static: false,
+  autocomplete: false
+}
+```
+
+Decidim works fine when some of the services are disabled individually but
+obviously, the disabled services are not available for Decidim users.
+
+### Global geocoder configurations
+
+In the Dedicim initialiser (`config/initializers/decidim.rb`) you will also see
+a commented section for the global geocoder configurations commented as follows:
+
+```ruby
+# Geocoder configurations ...
+# config.geocoder = {
+#   # geocoding service request timeout, in seconds (default 3):
+#   timeout: 5,
+#   # set default units to kilometers:
+#   units: :km,
+#   # caching (see https://github.com/alexreisner/geocoder#caching for details):
+#   cache: Redis.new,
+#   cache_prefix: "..."
+# }
+```
+
+This will change the global geocoding settings for your application. To learn
+more about these settings, take a look at the
+[Geocoder gem's documentation][link-geocoder].
+
+### Geocoding autocompletion configurations
+
+Each autocompletion geocoder has their own configurations and this may not apply
+for all geocoding services. The geocoder autocompletion integrations shipped
+with Decidim support the configurations shown in this section.
+
+If you want to customize the address format in the geocoding autocompletion
+fields, you can apply the following configuration to your geocoder settings:
+
+```ruby
+config.maps = {
+  # ... other configs ...
+  autocomplete: {
+    # For HERE:
+    address_format: [%w(street houseNumber), "city", "country"]
+    # For OSM/Photon:
+    # address_format: ["name", %w(street housenumber), "city", "country"]
+  }
+}
+```
+
+### Integrating with a new service provider
+
+If you want to integrate the map functionality with a new service provider, take
+a look at the [Custom map providers][link-docs-custom-maps] documentation.
+
+## Enabling maps and geocoding
+
+Once the maps functionality is configured, you'll need to activate it. As of
+April 2017, only proposals and meetings have maps and geocoding.
+
+### Proposals
+
+In order to enable geocoding for proposals you'll need to edit the component
+configuration and turn on "Geocoding enabled" configuration. This works for that
+specific component, so you can have geocoding enabled for proposals in a
+participatory process, and disabled for another proposals component in the same
+participatory process.
+
+### Meetings
+
+Meetings do not have a configuration option for geocoding. Instead, if geocoding
+is configured it will try to geocode the address every time you create or update
+a meeting. As of April 2017 there is no way to enable or disable geocoding per
+meetings component.
+
+## Hosting your own map services
+
+It is recommended to use a commercial service provider for all the map
+functionality to get up and running more easily. Hosting all these services
+yourself and keeping everything up to date is time consuming and rather complex.
+If the related complexity or the required time is not an issue, feel free to
+setup the following services on your own servers.
+
+### Map tiles: Open Street Maps tile server
+
+You will need a [map tiles][link-wiki-map-tiles] server which is used for the
+dynamic maps that the user can move themselves.
+
+Follow these instructions to setup your tiles server:
+
+https://opentileserver.org/
+
+In the example configuration, we assume you have used the following domain for
+the tiles server:
+
+https://tiles.example.org
+
+### Static map images: Openstreetmap static maps server (osm-static-maps)
+
+Some pages in Decidim display static map images which need to be fetched from
+an external server. The tiles server does not provide such static images by
+itself because one static map image may need multiple tiles to be combined into
+one. The static map image is therefore dynamically generated based on the
+parameters passed for the static map request (such as image dimensions and the
+geocoordinates of the map image position).
+
+The Open Street Maps community has made multiple open source
+[static maps image services][link-wiki-static-maps] from which you can pick
+freely but Decidim currently supports only
+[osm-static-maps][link-osm-static-maps] with the Open Street Maps services.
+
+Follow these instructions to setup your static map images server:
+
+https://github.com/jperelli/osm-static-maps#3-standalone-sample-server
+
+In the example configuration, we assume you have used the following domain for
+the static maps image server:
+
+https://staticmap.example.org
+
+Setting up this service is optional. If you do not configure a static map URL
+for the OSM based map services, Decidim will use the dynamic map tiles to
+generate a similar map element.
+
+### Geocoding: Nominatim geocoding server
+
+[Nominatim][link-osm-nominatim] makes it possible to place points on the Decidim
+maps based on addresses. This service provides geocoding capabilities by turning
+human readable addresses to [geographic coordinates][link-wiki-geocoordinates].
+
+Follow these instructions to setup your geocoding server:
+
+http://nominatim.org/release-docs/latest/admin/Installation/
+
+In the example configuration, we assume you have used the following domain for
+the geocoding server:
+
+https://nominatim.example.org
+
+### Geocoding autocompletion: Photon geocoding server
+
+[Photon][link-osm-photon] makes it possible to provide the autocompletion
+service for people writing addresses to the address fields available in Decidim.
+It uses the Open Street Maps data to serve the autocompletion requests. When
+people select one of the suggested addresses, it will also tell Decidim the map
+point for that address.
+
+Follow these instructions to setup your geocoding autocompletion server:
+
+https://github.com/komoot/photon#installation
+
+In the example configuration, we assume you have used the following domain for
+the Photon geocoding server for the autocompletion functionality:
+
+https://photon.example.org
+
+### Configure Decidim
+
+After you have all these services running, change your Decidim configurations
+to use these services. Read the
+[Configuring Open Street Maps based service providers][anchor-configure-osm]
+section for more information.
+
+[anchor-hosting-osm]: #hosting-your-own-map-services
+[anchor-configure-here-maps]: #configuring-here-maps
+[anchor-configure-osm]: #configuring-open-street-maps-based-service-providers
+[link-docs-custom-maps]: /docs/customization/maps.md
+[link-here]: http://here.com
+[link-geocoder]: https://github.com/alexreisner/geocoder
+[link-osm-commercial]: https://wiki.openstreetmap.org/wiki/Commercial_OSM_Software_and_Services
+[link-osm-nominatim]: https://wiki.openstreetmap.org/wiki/Nominatim
+[link-osm-static-maps]: https://github.com/jperelli/osm-static-maps
+[link-osm-photon]: https://github.com/komoot/photon
+[link-osm-tile-usage]: https://operations.osmfoundation.org/policies/tiles/
+[link-wiki-geocoordinates]: https://en.wikipedia.org/wiki/Geographic_coordinate_system
+[link-wiki-map-tiles]: https://wiki.openstreetmap.org/wiki/Tiles
+[link-wiki-static-maps]: https://wiki.openstreetmap.org/wiki/Static_map_images