decidim 0.23.6 → 0.24.0.rc1

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of decidim might be problematic. Click here for more details.

Files changed (114) hide show
  1. checksums.yaml +4 -4
  2. data/Rakefile +1 -0
  3. data/docs/README.adoc +74 -0
  4. data/docs/antora.yml +7 -0
  5. data/docs/modules/configure/pages/environment_variables.adoc +69 -0
  6. data/docs/modules/configure/pages/index.adoc +16 -0
  7. data/docs/modules/configure/pages/initializer.adoc +376 -0
  8. data/docs/modules/customize/assets/images/header-snippet.png +0 -0
  9. data/docs/modules/customize/assets/images/menu.png +0 -0
  10. data/docs/modules/customize/assets/images/organization-colors.png +0 -0
  11. data/docs/modules/customize/pages/authorizations.adoc +22 -0
  12. data/docs/{customization/code.md → modules/customize/pages/code.adoc} +12 -9
  13. data/docs/{customization/gemfile.md → modules/customize/pages/gemfile.adoc} +5 -4
  14. data/docs/modules/customize/pages/images.adoc +7 -0
  15. data/docs/modules/customize/pages/javascript.adoc +59 -0
  16. data/docs/modules/customize/pages/menu.adoc +25 -0
  17. data/docs/modules/customize/pages/oauth.adoc +33 -0
  18. data/docs/modules/customize/pages/styles.adoc +64 -0
  19. data/docs/modules/customize/pages/texts.adoc +30 -0
  20. data/docs/modules/customize/pages/users_registration_mode.adoc +17 -0
  21. data/docs/{customization/views.md → modules/customize/pages/views.adoc} +13 -13
  22. data/docs/modules/develop/assets/images/barcelona.png +0 -0
  23. data/docs/modules/develop/assets/images/helsinki.png +0 -0
  24. data/docs/modules/develop/assets/images/indices.png +0 -0
  25. data/docs/{advanced/api.md → modules/develop/pages/api.adoc} +2 -2
  26. data/docs/{advanced/authorship.md → modules/develop/pages/authorable.adoc} +5 -5
  27. data/docs/modules/develop/pages/c4_component.adoc +91 -0
  28. data/docs/modules/develop/pages/c4_container.adoc +42 -0
  29. data/docs/modules/develop/pages/c4_context.adoc +35 -0
  30. data/docs/{advanced/components.md → modules/develop/pages/components.adoc} +47 -10
  31. data/docs/{advanced/content_blocks.md → modules/develop/pages/content_blocks.adoc} +16 -13
  32. data/docs/{advanced/content_processors.md → modules/develop/pages/content_processors.adoc} +25 -19
  33. data/docs/modules/develop/pages/data-picker.adoc +85 -0
  34. data/docs/modules/develop/pages/deploy.adoc +15 -0
  35. data/docs/modules/develop/pages/docker.adoc +12 -0
  36. data/docs/{advanced/embeddable.md → modules/develop/pages/embeddable.adoc} +6 -6
  37. data/docs/{advanced/endorsable.md → modules/develop/pages/endorsable.adoc} +31 -25
  38. data/docs/{advanced/fixing_locales.md → modules/develop/pages/fixing_locales.adoc} +36 -23
  39. data/docs/{advanced/followers.md → modules/develop/pages/followable.adoc} +9 -8
  40. data/docs/modules/develop/pages/guide.adoc +16 -0
  41. data/docs/modules/develop/pages/guide_architecture.adoc +17 -0
  42. data/docs/modules/develop/pages/guide_changelog.adoc +8 -0
  43. data/docs/modules/develop/pages/guide_commands.adoc +86 -0
  44. data/docs/modules/develop/pages/guide_development_app.adoc +44 -0
  45. data/docs/modules/develop/pages/guide_development_with_custom_seed_data.adoc +31 -0
  46. data/docs/modules/develop/pages/guide_development_with_localhost_ssl.adoc +63 -0
  47. data/docs/modules/develop/pages/guide_example_apps.adoc +59 -0
  48. data/docs/modules/develop/pages/guide_git_conventions.adoc +75 -0
  49. data/docs/modules/develop/pages/guide_github_projects.adoc +42 -0
  50. data/docs/modules/develop/pages/guide_semver.adoc +7 -0
  51. data/docs/{advanced/how_to_fix_metrics.md → modules/develop/pages/how_to_fix_metrics.adoc} +76 -59
  52. data/docs/modules/develop/pages/machine_translations.adoc +42 -0
  53. data/docs/modules/develop/pages/managing_translations_i18n.adoc +24 -0
  54. data/docs/modules/develop/pages/maps.adoc +499 -0
  55. data/docs/modules/develop/pages/metrics.adoc +119 -0
  56. data/docs/{advanced/modules.md → modules/develop/pages/modules.adoc} +16 -6
  57. data/docs/{advanced/newsletter_templates.md → modules/develop/pages/newsletter_templates.adoc} +12 -10
  58. data/docs/{advanced/notifications.md → modules/develop/pages/notifications.adoc} +40 -38
  59. data/docs/{advanced/open-data.md → modules/develop/pages/open-data.adoc} +4 -3
  60. data/docs/modules/develop/pages/permissions.adoc +92 -0
  61. data/docs/{advanced/profiling.md → modules/develop/pages/profiling.adoc} +15 -12
  62. data/docs/modules/develop/pages/releases.adoc +148 -0
  63. data/docs/modules/develop/pages/reportable.adoc +31 -0
  64. data/docs/modules/develop/pages/security.adoc +33 -0
  65. data/docs/{advanced/share_tokens.md → modules/develop/pages/share_tokens.adoc} +18 -14
  66. data/docs/{advanced/templates.md → modules/develop/pages/templates.adoc} +14 -12
  67. data/docs/{advanced/testing.md → modules/develop/pages/testing.adoc} +21 -20
  68. data/docs/{advanced/activity_log.md → modules/develop/pages/traceable.adoc} +31 -26
  69. data/docs/modules/develop/pages/turbolinks.adoc +7 -0
  70. data/docs/{advanced/view_hooks.md → modules/develop/pages/view_hooks.adoc} +29 -23
  71. data/docs/modules/develop/pages/view_models_aka_cells.adoc +105 -0
  72. data/docs/modules/install/pages/checklist.adoc +39 -0
  73. data/docs/modules/install/pages/index.adoc +148 -0
  74. data/docs/{manual-installation.md → modules/install/pages/manual.adoc} +54 -42
  75. data/docs/modules/install/pages/update.adoc +95 -0
  76. data/docs/{services/activejob.md → modules/services/pages/activejob.adoc} +3 -3
  77. data/docs/modules/services/pages/elections_bulletin_board.adoc +52 -0
  78. data/docs/{services/etherpad.md → modules/services/pages/etherpad.adoc} +15 -12
  79. data/docs/modules/services/pages/maps.adoc +311 -0
  80. data/docs/modules/services/pages/smtp.adoc +10 -0
  81. data/docs/modules/services/pages/social_providers.adoc +122 -0
  82. data/lib/decidim/gem_manager.rb +5 -5
  83. data/lib/decidim/version.rb +1 -1
  84. metadata +137 -100
  85. data/README.md +0 -157
  86. data/docs/advanced/add_authorizable_action.md +0 -63
  87. data/docs/advanced/adding_fixtures_aka_dummy_content.md +0 -9
  88. data/docs/advanced/data-picker.md +0 -83
  89. data/docs/advanced/deploy.md +0 -9
  90. data/docs/advanced/how_to_create_a_module.md +0 -9
  91. data/docs/advanced/machine_translation_service.md +0 -12
  92. data/docs/advanced/managing_translations_i18n.md +0 -24
  93. data/docs/advanced/metrics.md +0 -114
  94. data/docs/advanced/permissions.md +0 -23
  95. data/docs/advanced/releases.md +0 -114
  96. data/docs/advanced/tradeoffs.md +0 -14
  97. data/docs/advanced/view_models_aka_cells.md +0 -99
  98. data/docs/checklist.md +0 -55
  99. data/docs/customization/authorizations.md +0 -5
  100. data/docs/customization/images.md +0 -7
  101. data/docs/customization/javascript.md +0 -9
  102. data/docs/customization/machine_translations.md +0 -30
  103. data/docs/customization/maps.md +0 -610
  104. data/docs/customization/oauth.md +0 -50
  105. data/docs/customization/styles.md +0 -11
  106. data/docs/customization/texts.md +0 -27
  107. data/docs/customization/users_registration_mode.md +0 -17
  108. data/docs/development_guide.md +0 -166
  109. data/docs/getting_started.md +0 -191
  110. data/docs/possible_flows_for_proposal.png +0 -0
  111. data/docs/services/analytics.md +0 -23
  112. data/docs/services/elections_bulletin_board.md +0 -38
  113. data/docs/services/maps.md +0 -362
  114. data/docs/services/social_providers.md +0 -98
@@ -1,36 +1,39 @@
1
- # How to profile a Decidim app
1
+ = How to profile a Decidim app
2
2
 
3
- The developmen_app includes a bunch of gems that profile the application. Run the following command in the decidim root's folder:
3
+ The development_app includes a bunch of gems that profile the application. Run the following command in the decidim root's folder:
4
4
 
5
- ```bash
5
+ [source,bash]
6
+ ----
6
7
  bundle exec rake development_app
7
- ```
8
+ ----
8
9
 
9
10
  and then move into it and boot the server
10
11
 
11
- ```bash
12
- cd developmen_app
12
+ [source,bash]
13
+ ----
14
+ cd development_app
13
15
  bundle exec rails s
14
- ```
16
+ ----
15
17
 
16
- ## Bullet
18
+ == Bullet
17
19
 
18
20
  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:
19
21
 
20
- ```bash
22
+ [source,bash]
23
+ ----
21
24
  user: xxx
22
25
  GET /
23
26
  USE eager loading detected
24
27
  Decidim::Comments::Comment => [:author]
25
28
  Add to your query: .includes([:author])
26
29
  Call stack
27
- ```
30
+ ----
28
31
 
29
32
  It also warns you when there's an unnecessary eager load.
30
33
 
31
34
  More details: https://github.com/flyerhzm/bullet
32
35
 
33
- ## Rack-mini-profiler
36
+ == Rack-mini-profiler
34
37
 
35
38
  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.
36
39
 
@@ -38,6 +41,6 @@ This gem is further enhanced with the `flamegraph`, `stackprof` and `memory_prof
38
41
 
39
42
  More details: https://github.com/MiniProfiler/rack-mini-profiler
40
43
 
41
- ## Profiling best practices
44
+ == Profiling best practices
42
45
 
43
46
  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.
@@ -0,0 +1,148 @@
1
+ = Releasing new versions
2
+
3
+ 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.
4
+
5
+ Remember to follow the Gitflow branching workflow.
6
+
7
+ == Create the stable branch for the release
8
+
9
+ . Go to develop with `git checkout develop`
10
+ . Create the release branch `git checkout -b release/x.y-stable && git push origin release/x.y-stable`.
11
+ . If required, add the release branch to Crowdin so that any pending translations will generate a PR to this branch.
12
+
13
+ Mark `develop` as the reference to the next release:
14
+
15
+ . Go back to develop with `git checkout develop`
16
+ . Turn develop into the `dev` branch for the next release:
17
+ .. 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
18
+ .. Run `bin/rake update_versions`, this will update all references to the new version.
19
+ .. Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
20
+ .. Run `bin/rake webpack`, this will update the JavaScript bundle.
21
+ . Update `SECURITY.md` and change the supported version to the new version.
22
+ . Update the `CHANGELOG.MD`.
23
+ At the top you should have an `Unreleased` header with the `Added`, `Changed`, `Fixed` and `Removed` empty sections.
24
+ 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.
25
+
26
+ [source,markdown]
27
+ ----
28
+ ## [Unreleased](https://github.com/decidim/decidim/tree/HEAD)
29
+
30
+ ### Added
31
+
32
+ ### Changed
33
+
34
+ ### Fixed
35
+
36
+ ### Removed
37
+
38
+ ## [v0.XX.0](https://github.com/decidim/decidim/releases/tag/v0.XX.0)
39
+
40
+ ### Added
41
+ ...
42
+
43
+ ## Previous versions
44
+
45
+ Please check [0.XX-stable](https://github.com/decidim/decidim/blob/release/0.XX-stable/CHANGELOG.md) for previous changes.
46
+ ----
47
+
48
+ . Push the changes `git add . && git commit -m "Bump develop to next release version" && git push origin develop`
49
+
50
+ == Producing the CHANGELOG.md
51
+
52
+ Look for the "Bump develop to next release version" commit sha1.
53
+ You can do it either visually with `gitk .decidim-version` or by blaming `git blame .decidim-version`.
54
+
55
+ Here you have different options to see what happened from one revision to another:
56
+
57
+ [source,bash]
58
+ ----
59
+ git log v0.20.0..v0.20.1 --grep " (#[0-9]\+)" --oneline
60
+ git log <SHA>..HEAD --grep " (#[0-9]\+)" --oneline
61
+ ----
62
+
63
+ Once you've checked the list of changes, it's time to actually generating the changelog.
64
+
65
+ [source,bash]
66
+ ----
67
+ bin/changelog_generator
68
+ ----
69
+
70
+ 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:
71
+
72
+ [source,bash]
73
+ ----
74
+ bin/changelog_generator <GITHUB_TOKEN> <SHA>
75
+ ----
76
+
77
+ 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.
78
+
79
+ You can copy-paste the output of the command to the relevant sections of the changelog file.
80
+
81
+ == Release Candidates
82
+
83
+ Release Candidates are the same as beta versions.
84
+ They should be ready to go to production, but publicly released just before in order to be widely tested.
85
+
86
+ If this is a *Release Candidate version* release, the steps to follow are:
87
+
88
+ . Checkout the release stable branch `git checkout release/x.y-stable`.
89
+ . Update `.decidim-version` to the new version `x.y.z.rc1`
90
+ . Run `bin/rake update_versions`, this will update all references to the new version.
91
+ . Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
92
+ . Run `bin/rake webpack`, this will update the JavaScript bundle.
93
+ . Commit all the changes: `git add . && git commit -m "Bump to rcXX version" && git push origin release/x.y-stable`.
94
+ . Tag the release candidate with `git tag vX.Y.Z.rcN && git push origin vX.Y.Z.rcN`.
95
+
96
+ Usually, at this point, the release branch is deployed to Metadecidim during, at least, one week to validate the stability of the version.
97
+
98
+ === During the validation period
99
+
100
+ . During the validation period, bugfixes must be implemented directly to the current `release/x.y.z-stable` branch and ported to `develop`.
101
+ . 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`.
102
+
103
+ == Major/Minor versions
104
+
105
+ 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:
106
+
107
+ . Checkout the release stable branch `git checkout release/x.y-stable`.
108
+ . Update `.decidim-version` by removing the `.rcN` suffix, leaving a clean version number like `x.y.z`
109
+ . Run `bin/rake update_versions`, this will update all references to the new version.
110
+ . Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
111
+ . Run `bin/rake webpack`, this will update the JavaScript bundle.
112
+ . Update `CHANGELOG.MD`.
113
+ At the top you should have an `Unreleased` header with the `Added`, `Changed`, `Fixed` and `Removed` empty sections.
114
+ 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.
115
+ . Commit all the changes: `git add . && git commit -m "Bump to v0.XX.0 final version" && git push origin release/x.y-stable`.
116
+ . Run `git pull && bin/rake release_all`, this will create all the tags, push the commits and tags and release the gems to RubyGems.
117
+ . 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.
118
+ . Update Decidim's Docker repository as explained in the Docker images section below.
119
+ . Update Crowdin synchronization configuration with Github:
120
+ .. Add the new `release/x.y-stable` branch.
121
+ .. Remove from Crowdin branches that are not officially supported anymore.
122
+ That way they don't synchronize with Github.
123
+ . Update the `CHANGELOG.MD` in `release/x.y-stable`.
124
+ At the top you should have an `Unreleased` header with the `Added`, `Changed`, `Fixed` and `Removed` empty sections.
125
+ After that, the header with the current version.
126
+ Add the `Unreleased` section or create the new current version section.
127
+
128
+ == Releasing patch versions
129
+
130
+ Releasing new versions from a *_release/x.y-stable_* branch is quite easy.
131
+ The process is very similar from releasing a new Decidim version:
132
+
133
+ . Checkout the branch you want to release: `git checkout -b release/x.y-stable`
134
+ . Update `.decidim-version` to the new version number.
135
+ . Run `bin/rake update_versions`, this will update all references to the new version.
136
+ . Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
137
+ . Run `bin/rake webpack`, this will update the JavaScript bundle.
138
+ . Update `CHANGELOG.MD`.
139
+ At the top you should have an `Unreleased` header with the `Added`, `Changed`, `Fixed` and `Removed` empty sections.
140
+ 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.
141
+ . Commit all the changes: `git add . && git commit -m "Prepare VERSION release"`
142
+ . Run `bin/rake release_all`, this will create all the tags, push the commits and tags and release the gems to RubyGems.
143
+ . 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.
144
+ . Update Decidim's Docker repository as explained in the Docker images section.
145
+
146
+ == Docker images for each release
147
+
148
+ 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].
@@ -0,0 +1,31 @@
1
+ = Reportable
2
+
3
+ == Resources can be reportable
4
+
5
+ `Reportable` is a feature that allows Decidim resources to be reported by users.
6
+ A resource can be reported by a user as 'spam', 'offensive' or 'does_not_belong'.
7
+
8
+ When a resource is reported, a `Report` is created.
9
+ All ``Report``s of a resource are grouped in a `Moderation` and can be moderated by the admins.
10
+
11
+ A `Reportable` is expected to implement:
12
+
13
+ * `reported_content_url`: the URL for the reportable resource;
14
+ * `reported_attributes`: a list of attributes that can be reported (e.g.
15
+ `[:title, :body]`) - used to display the report content by the `ReportedContentCell`;
16
+ * `reported_searchable_content_extras` (optional): a list of attributes other than `reported_attributes` the report can be search by (e.g.
17
+ `[author.name]`) - used in the reports search bar of the admin panel.
18
+
19
+ == Public view
20
+
21
+ === The ReportedContentCell
22
+
23
+ The reccomended way to render the content of a `Reportable` is with a `decidim/reported_content` cell.
24
+
25
+ [source,ruby]
26
+ ----
27
+ cell("decidim/reported_content", reportable)
28
+ ----
29
+
30
+ By default, this will render the generic `Decidim::ReportedContentCell`.
31
+ You can also customize the template for your `Reportable` by extending `Decidim::ReportedContentCell` (see `Decidim::Proposal::ReportedContentCell`)
@@ -0,0 +1,33 @@
1
+ = Security Policy
2
+
3
+ == Supported Versions
4
+
5
+ Until we have the version 1.0 we support only the last minor and major
6
+ version with security updates.
7
+
8
+ |===
9
+ | Version | Supported
10
+
11
+ | 0.21.x
12
+ | :white_check_mark:
13
+
14
+ | \<= 0.20
15
+ | :x:
16
+ |===
17
+
18
+ == Reporting a Vulnerability
19
+
20
+ Security is very important to us.
21
+
22
+ If you have any issue regarding security, please disclose the information
23
+ responsibly by sending an email to security [at] decidim [dot] org and not
24
+ by creating a github/metadecidim issue. We appreciate your effort to make
25
+ Decidim more secure.
26
+
27
+ We recommend to use GPG for these kind of communications, the fingerprint
28
+ is `C1BD 8981 D83C 23F9 D419 FE42 149A D0F9 84B9 35C4`. To download our key:
29
+
30
+ [source,bash]
31
+ ----
32
+ gpg --keyserver pgp.key-server.io --recv 84B935C4
33
+ ----
@@ -1,53 +1,57 @@
1
- # Share tokens
1
+ = Share tokens
2
2
 
3
3
  Share tokens can be assigned to any model to provide a system to share unpublished resources with expirable and manageable tokens.
4
4
 
5
5
  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.
6
6
 
7
- ## Add share tokens to a model
7
+ == Add share tokens to a model
8
8
 
9
9
  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.
10
10
 
11
- ```ruby
11
+ [source,ruby]
12
+ ----
12
13
  # Public: Public URL for your_resource with given share token as query parameter
13
14
  def shareable_url(share_token)
14
15
  your_resource_public_path(self, share_token: share_token.token)
15
16
  end
16
- ```
17
+ ----
17
18
 
18
- ## Set permissions
19
+ == Set permissions
19
20
 
20
- 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).
21
+ 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).
21
22
 
22
23
  It should do something similar to this:
23
24
 
24
- ```ruby
25
+ [source,ruby]
26
+ ----
25
27
  token = context[:share_token]
26
28
 
27
29
  return unless token.present?
28
30
 
29
31
  allow! if Decidim::ShareToken.use!(token_for: your_resource, token: token)
30
- ```
32
+ ----
31
33
 
32
- ## Manage tokens
34
+ == Manage tokens
33
35
 
34
36
  Render the partial `decidim-admin/app/views/decidim/admin/share_tokens/_share_tokens.html.erb` inside a view, with:
35
37
 
36
- ```ruby
38
+ [source,ruby]
39
+ ----
37
40
  locals: { share_tokens: your_share_tokens_variable }
38
- ```
41
+ ----
39
42
 
40
43
  to let admins see and manage tokens for that resource.
41
44
 
42
- ## Link to url with token
45
+ == Link to url with token
43
46
 
44
47
  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`.
45
48
 
46
- ```ruby
49
+ [source,ruby]
50
+ ----
47
51
  def share
48
52
  @your_resource = YourResource.find(params[:id]) # or whatever
49
53
  share_token = @your_resource.share_tokens.create!(user: current_user, organization: current_organization)
50
54
 
51
55
  redirect_to share_token.url
52
56
  end
53
- ```
57
+ ----
@@ -1,24 +1,25 @@
1
- # Templates
1
+ = Templates
2
2
 
3
3
  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.
4
4
 
5
- ## Model
5
+ == Model
6
6
 
7
7
  The only requisite to create a template for a model is that the model class includes the `Decidim::Templates::Templatable` concern.
8
8
 
9
- ## Controller
9
+ == Controller
10
10
 
11
11
  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.
12
12
 
13
- ## Commands
13
+ == Commands
14
14
 
15
15
  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.
16
16
 
17
- ## Routes
17
+ == Routes
18
18
 
19
19
  The following routes should be defined in `decidim-templates/lib/decidim/templates/admin_engine.rb`.
20
20
 
21
- ```ruby
21
+ [source,ruby]
22
+ ----
22
23
  resources :$MODEL_templates do
23
24
  member do
24
25
  post :copy
@@ -32,25 +33,26 @@ resources :$MODEL_templates do
32
33
  get :preview # To provide a preview for the template in the object creation view
33
34
  end
34
35
  end
35
- ```
36
+ ----
36
37
 
37
- ## Views
38
+ == Views
38
39
 
39
40
  All views related to a model's template management must be created inside `decidim-templates/app/views/decidim/templates/admin/$MODEL_templates`.
40
41
 
41
- ## Testing
42
+ == Testing
42
43
 
43
44
  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.
44
45
 
45
- ## Other
46
+ == Other
46
47
 
47
48
  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.
48
49
 
49
- ```ruby
50
+ [source,ruby]
51
+ ----
50
52
  def template_types
51
53
  @template_types ||= {
52
54
  I18n.t("template_types.questionnaires", scope: "decidim.templates") => decidim_admin_templates.questionnaire_templates_path,
53
55
  I18n.t("template_types.$MODEL_PLURAL", scope: "decidim.templates") => decidim_admin_templates.$MODEL_templates_path,
54
56
  }
55
57
  end
56
- ```
58
+ ----
@@ -1,48 +1,49 @@
1
- # How to test Decidim engines
1
+ = How to test Decidim engines
2
2
 
3
- ## Requirements
3
+ == Requirements
4
4
 
5
5
  You need to create a dummy application to run your tests. Run the following command in the decidim root's folder:
6
6
 
7
- ```bash
7
+ [source,bash]
8
+ ----
8
9
  bundle exec rake test_app
9
- ```
10
+ ----
10
11
 
11
- ## Running a specific test file or just a single spec
12
+ == Running a specific test file or just a single spec
12
13
 
13
- 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:
14
+ 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:
14
15
 
15
- ```bash
16
+ [source,bash]
17
+ ----
16
18
  cd decidim-participatory_processes
17
19
  bundle exec rspec spec/forms/participatory_process_form_spec.rb
18
- ```
20
+ ----
19
21
 
20
22
  You can also run a single test by appending its start line number to the command:
21
23
 
22
- ```bash
24
+ [source,bash]
25
+ ----
23
26
  bundle exec rspec spec/forms/participatory_process_form_spec.rb:134
24
- ```
27
+ ----
25
28
 
26
- ## Running tests for a specific component
29
+ == Running tests for a specific component
27
30
 
28
31
  A Decidim engine can be tested running the rake task named after it. For
29
32
  example, to test the proposals engine, you can run:
30
33
 
31
- ```bash
34
+ [source,bash]
35
+ ----
32
36
  bundle exec rake test_proposals
33
- ```
37
+ ----
34
38
 
35
- ## Running the whole test suite
39
+ == Running the whole test suite
36
40
 
37
41
  You can also run the full thing including test application generation and tests
38
42
  for all components by running
39
43
 
40
- ```bash
44
+ [source,bash]
45
+ ----
41
46
  bundle exec rake test_all
42
- ```
47
+ ----
43
48
 
44
49
  But beware, it takes a long time... :)
45
-
46
- ## Make CircleCI not run tests for a specific commit
47
-
48
- If you want that CircleCI no run tests for a specific commit, add this in your commit message `[ci_skip]`