What upgrades and support cover for Decidim
Before version 1.0, Decidim supports only the last two minor versions with security updates, currently 0.32.x and 0.31.x. Versions 0.30.x and earlier are outside support, so an older instance has to move forward one minor version at a time, for example 0.29 to 0.30 before 0.31. For each step, follow that release's upgrade instructions, since some releases change database structures, and take a database backup first. Check your current version against the release list before you build the upgrade calendar.
Several events start an upgrade. An instance may fall out of the supported pair, a security advisory may set a patch window, or a Ruby or Rails change may be required. Version 0.32 moves to Ruby 3.4.7 and Rails 8.1, for example. A new feature your organization wants, or a custom module that breaks when core code changes, can also trigger the work. Security deadlines are fixed: Decidim's security policy gives implementers 2 months for standard vulnerabilities and 4 months for critical ones before details are disclosed. Put those dates in your calendar as soon as an advisory arrives.
Many teams with an in-house Rails developer and a clear upgrade calendar keep this work internal, provided they test custom modules on a staging copy before production. Teams without that capacity usually bring in a partner for the first upgrade and then retain support. When you request a quote, state the starting version, the target version, each custom module and integration in scope, and whether staging, rollback and post-upgrade testing are included. Ask for the scope in writing before work begins.
What the work includes
The upgrade engagement is split into assessment, rehearsal, cutover and handover, with an optional retainer for security releases. Each card is a work package you can check against your own environment and a partner's proposal.
Current-state assessment
We record the installed Decidim version, Ruby and Node versions, PostgreSQL version, enabled components, custom modules, OmniAuth providers, and ActiveStorage and ActiveJob configuration. Target versions drive the gap: v0.32 requires Ruby 3.4.7 and Node 22.14.x, while v0.31 uses Ruby 3.3.4. Confirm each of these against your running instance before scoping.
Step-by-step minor version plan
Decidim's update guide asks for one minor version at a time, following each release's own upgrade instructions because some change database structures. The plan lists each hop, its migrations, its runtime changes, and the point where a backup is taken before it runs. Ask the partner to show the hop sequence in writing.
Staging rehearsal
Each hop is run first on a copy of production data with the same configuration, plugins and background workers. The rehearsal records migration time, errors and any manual steps. Its output sets the window and the cutover checklist, so the production run has no unknowns left.
Production cutover with rollback
The cutover follows the rehearsed checklist: full database backup, file storage snapshot, maintenance mode, migration, service restart and smoke tests. A rollback path is defined and tested before the window opens, including how to restore the database and reattach file storage if a hop fails.
Custom module and theme fixes
Custom modules and themes are checked against each target release's APIs, views and asset pipeline. Fixes are made in your repository, with tests where they exist. Ask which modules have automated tests, because untested modules carry more regression risk during each hop.
Verification and login checks
After each hop we verify participant registration, login through every configured OmniAuth provider, email delivery through SMTP, background job processing, file uploads and downloads, map and geocoding features, and any authorization handler used for voting or signing. Results are logged against each check.
Handover documentation
Handover covers the runbook for future minor upgrades, the environment configuration, and notes on known customizations. Your team should be able to repeat a hop without the partner in the room. Ask for a dry run with your staff before the engagement closes.
Security patch retainer
The optional retainer covers monitoring of Decidim security releases and applying patches within the grace periods Decidim describes: 2 months for standard vulnerabilities and 4 months for critical ones before details are disclosed. Confirm response times, staging coverage and who approves production changes in the written scope.
What drives effort and duration
This table lists the factors that most change how much work a Decidim upgrade or support engagement takes, why each one matters, and what to do to keep it in check.
| Driver | Why it matters | How to keep it down |
|---|---|---|
| Minor versions between current and target | Decidim upgrades one minor version at a time, so each step adds a full cycle of upgrade notes, test runs and database migrations. Older instances move further from the two supported releases with each gap. | Upgrade on a regular cadence rather than letting the instance fall behind. Confirm the exact path with the update guide before quoting. |
| Custom modules and forks of core code | Custom modules must be checked against each release's changed APIs and models. A fork of core code must be rebased or re-applied on every upgrade, which usually adds the most effort. | Keep customizations in separate modules that use public extension points. Minimize forks and document every patch so it can be replayed. |
| Theme and template overrides | Overridden views and stylesheets often break when core markup or components change, and visual regressions are easy to miss without page-level review. | Limit overrides to what branding needs. Keep them in a theme module and include the key public pages in regression checks. |
| OmniAuth providers and identity integrations | Each provider or identity link (social login, national eID, organizational identity provider) has its own configuration, callback URLs and test accounts that must be verified after an upgrade. | Use only the providers the organization needs. Keep a per-provider test checklist with sandbox credentials for each one. |
| Data volume and database migration size | Migrations run against the full database, so large participation histories, proposals and comments lengthen the migration window and the backup and restore cycle. | Archive or prune old data where policy allows. Rehearse the migration on a recent copy of production to measure timing. |
| File storage volume | Attachments stored through ActiveStorage must be backed up, copied to staging for testing and checked for integrity, which adds time to every rehearsal and cutover. | Plan storage and backups together. Confirm how the storage backend is copied to test environments and how long a full copy takes. |
| Number of environments | Each upgrade must be applied and tested in development, staging and production. Gaps between environments create drift that makes later steps harder to reproduce. | Keep environments built from the same configuration and container images. Promote the same tested artifacts rather than rebuilding them. |
| Organizations or tenants in one instance | Multi-organization setups share one codebase but have separate settings, providers and content. Every organization needs its own functional checks after the upgrade. | Define a standard smoke-test script covering each organization. Group organizations with similar configurations so checks can be shared. |
| Integrations with SMTP, maps and geocoding | Mail delivery, map tiles and geocoding services are external dependencies. Their credentials, endpoints and client libraries can change during an upgrade and fail silently. | Test outbound email and map features in staging with real provider settings. Keep a list of external endpoints and their owners. |
| Availability window | A short maintenance window forces a faster rehearsal, a tighter cutover and a rollback plan that can be executed quickly. Some releases may need more time than the window allows. | Agree the window and the rollback criteria before scheduling. Confirm the expected downtime from a rehearsal on production-sized data. |
| Ruby, Node and platform image changes | Each release sets Ruby and Node versions, and the manual install guide sets PostgreSQL and operating system versions. Changes can require rebuilt hosting images and dependency updates. | Read the requirements section of each release before starting. Build and test container images for the target versions in staging first. |
Upgrade and support phases
The sequence moves a Decidim instance one minor version at a time, proving each step in staging before production, and then keeps it on a supported release.
Inventory the current instance
Your team and DeployOpen record the installed Decidim version, Ruby and Node versions, PostgreSQL version, enabled components, custom modules, OmniAuth providers, authorization handlers and background job setup. The step closes with a written inventory that lists every custom change that must be re-tested or ported.
Select the target version and upgrade path
Decidim's update guide says to move one minor version at a time, for example 0.29 to 0.30 before 0.31, and to follow each release's own upgrade instructions because some change database structures. The step closes with a documented version sequence and a confirmed Ruby, Node and PostgreSQL requirement for each hop, checked against the release notes.
Prepare the runtime and environment
The team installs the Ruby and Node versions the chosen target requires, which the Decidim documentation lists as Ruby 3.4.7 and Node 22.14.x for v0.32 and Ruby 3.3.4 and Node 22.14.x for v0.31, and confirms the PostgreSQL version against the manual installation guide. The step closes when a staging host builds the current codebase and starts with the new runtime.
Upgrade staging and fix custom modules
The team restores a copy of production data to staging, applies the release's upgrade instructions and runs the migrations for that hop. Custom modules and overrides are adapted to the new version. The step closes when staging boots cleanly, migrations complete and the target version is recorded as running in staging.
Run acceptance tests on real workflows
Testers run the workflows participants and administrators depend on: sign-in through each configured login provider, identity verification, proposals, meetings, and the voting or signing steps that authorization rules restrict to verified participants. The step closes with a signed-off test record listing each workflow, its result and any open defects.
Cut over to production and monitor
The team takes a full database backup before anything changes, runs the upgrade in a scheduled maintenance window, and checks the application, background jobs, file storage, email and login. Monitoring then watches errors, job queues and authentication for a period agreed in the written scope. The step closes when the production health checks pass and the backup location is recorded.
Run the recurring support cycle
Decidim supports only the last two minor versions with security updates until version 1.0, so the instance must be moved onto a supported line on an ongoing basis. The team tracks new security releases, applies patches within the grace periods Decidim describes (2 months for standard vulnerabilities and 4 months for critical ones before disclosure), and repeats the upgrade cycle. The step closes with a dated patch log for each release.
What stays in-house and what to outsource
This table shows who usually carries each upgrade task, and the skill gap is usually Rails upgrades plus knowledge of Decidim's module structure.
| Task | Usually in-house | Usually outsourced | Skill required |
|---|---|---|---|
| Decide to upgrade and set the business calendar | Product owner sets upgrade timing around live processes, consultations and election periods. | Usually none. A partner may advise on the upgrade window. | Governance knowledge of live participatory processes and their dates. |
| Inventory custom code and content risk | Operators list custom modules, themes, data and the content owners for each space. | Developer reviews custom code against the target minor version. | Git history, Decidim module structure and content governance. |
| Rails and Ruby compatibility fixes for custom modules | Team keeps custom code in its own repository and reviews every change. | Rails developer ports custom modules to the Ruby and Rails versions the target release requires. | Rails upgrades plus knowledge of Decidim's module structure. |
| Infrastructure and PostgreSQL backup and restore | Internal team or hosting partner runs backups, restore tests and database configuration. | Hosting partner or DBA may own scheduled backup jobs and restore drills. | PostgreSQL administration, Linux operations and restore testing. |
| Staging rehearsal and acceptance testing | Participation team signs off on processes, components, content and branding. | Partner runs staging upgrade rehearsals and regression test scripts. | Test scripting plus staff knowledge of how live spaces are used. |
| Production cutover and rollback | Operators hold the change window and approve the rollback decision. | Partner executes the migration steps and the documented rollback plan. | Deployment runbooks, database migration handling and out-of-hours cover. |
| Ongoing monitoring of security advisories | A named owner tracks security notices and release announcements for the running version. | A retained partner watches releases and prepares patch upgrades on request. | Reading advisories and matching patch urgency to the disclosure grace periods. |
What usually goes wrong
Most Decidim upgrade problems come from skipped steps in the release process rather than from the platform itself. Each failure below has a prevention step that can be planned before the upgrade window opens.
Jumping ahead across minor versions
Teams sometimes move a Decidim instance from an older release straight to a newer one to save time. Decidim's update guide asks for one minor version at a time, for example 0.29 to 0.30 before 0.31. Prevent this by listing every intermediate release, upgrading each one in staging, and confirming the application runs before moving to the next step.
Release instructions and rehearsal skipped
Some releases change database structures, and their upgrade notes list steps the standard update does not cover. Teams that skip those notes, or run the first upgrade against live data, risk a failed migration with no tested way back. Prevent this by reading each release's instructions, taking a database backup, and rehearsing the full upgrade on a copy of production data.
Custom modules built on changed APIs
Custom modules and forks often depend on internal interfaces, and those can change between minor versions. A module that loads in staging can still fail at runtime when a model, helper or component it calls has moved. Prevent this by inventorying every custom module, reviewing each release's changes against it, and running its test suite against the target version before cutover.
Ruby, Rails or Node out of step
Each Decidim release names the Ruby, Node and database versions it runs on. Version 0.32 requires Ruby 3.4.7 and Node 22.14.x, while 0.31 uses Ruby 3.3.4 with the same Node line, so a server image reused from the previous upgrade can carry the wrong runtime. Prevent this by pinning runtime versions per release in the build and checking them before the migration starts.
Locale-prefixed URLs left behind
Decidim v0.32 uses locale-prefixed URLs, so paths that worked earlier may now point to the wrong page or fail. Custom menus, redirects, email links, reverse proxy rules and external integrations often still use the old form. Prevent this by inventorying every inbound and outbound link, adding redirects for old paths, and testing each integration against the new structure.
Support branch and patch windows missed
Until version 1.0, Decidim gives security updates only to the last two minor versions, currently 0.32.x and 0.31.x, so 0.30.x and earlier receive none. Implementers also get a 2-month grace period for standard vulnerabilities and 4 months for critical ones before details are disclosed. Prevent this by tracking the support window in the project plan, subscribing to security notices, and scheduling patch releases as recurring work.
How the work changes by starting point
An instance already on 0.31 has one move, to 0.32. The changes sit mainly in the runtime and the URL scheme, so the work is mostly build changes, configuration and testing.
- Ruby: move from 3.3.4 to 3.4.7, then rebuild gems and native extensions against the new runtime.
- Node: both releases use the 22.14.x line, so confirm the exact patch your build pipeline pins.
- Rails 8.1: review custom code and gems against the Rails 8.1 changes before the upgrade starts.
- Locale-prefixed URLs: check redirects, email links, social login callback URLs and external links to participatory spaces.
- Confirm before quoting: the 0.32 upgrade instructions, your current 0.31 patch level, and whether any custom component depends on routes that changed.
Decidim's update guide asks for one minor version at a time, so an instance several releases back becomes a sequence of upgrades. Each step carries its own database changes and its own instructions.
- Steps: each release needs a build, a migration run and a verification pass, so effort grows with the number of steps.
- Runtime: Ruby and Node requirements change along the path, so confirm the runtime each intermediate release needs.
- Security exposure: only the last two minor versions receive security updates, so older lines stay exposed until they reach a supported release. Confirm this window with your security team.
- Custom modules: check them at every step, not only at the final one.
- Confirm before quoting: the exact list of intermediate versions, a backup and rollback point for each step, and whether the team has already audited the current version.
Customization often affects the effort more than the version gap. Every custom module, theme, overridden view or patched core file must be reviewed against each target release.
- Inventory: list custom modules, overridden views, core patches and pinned gem versions before estimating.
- Fork maintenance: confirm whether the fork tracks upstream, since changes may need to be reapplied or rebased onto the new release.
- Schema changes: custom components that alter the database need their migrations reviewed alongside upstream migrations.
- Authentication: custom OmniAuth strategies, authorization handlers and social login providers need their own test pass.
- Confirm before quoting: who owns the fork, how custom code is tested, and whether any added code has licensing terms that differ from the AGPL-3.0 license of Decidim.
The deployment model sets where the upgrade runs and who controls the sequence. A manual Rails install, a Docker setup, a Kubernetes cluster and a managed host each need a different plan.
- Manual Rails: the team installs the runtimes and gems on the host, so every package and version is under local control.
- Docker: confirm whether images are built from upstream or from a local Dockerfile, and rebuild them for each target version.
- Kubernetes: confirm how database migrations run, and how web and background job workers are rolled so they do not run against a mismatched schema.
- Managed hosting: confirm which upgrades the provider performs, its maintenance windows, and whether it allows custom modules and direct database access.
- Confirm before quoting: the PostgreSQL version in use (the manual guide lists 17.4 or later), and who runs backups and restores.
When the network cannot reach public package registries or container hubs, every dependency must be mirrored inside the network before the upgrade starts.
- Mirrors: gems, npm packages, Ruby and Node runtimes and container images need internal copies.
- Build transfer: build the release bundle on a connected machine, verify checksums, then move it across the boundary with the same pinned versions.
- External services: email, maps, geocoding and social login depend on outside services, so confirm which remain reachable and which must be replaced or disabled.
- Advisories: confirm how the team receives security reports from the Decidim security contacts into the restricted network, and how it meets the patch grace periods.
- Confirm before quoting: the mirror refresh schedule, who moves artifacts across the boundary, and the approval steps for each transfer.
What you need to provide
The upgrade team can only work as fast as the access and decisions you provide. Before scoping starts, confirm that you can supply access to the production and staging environments and to the deployment pipeline, the current Decidim version, and a copy of the Gemfile and configuration files. Without the exact Gemfile.lock state and the organization configuration, the team cannot reproduce your running instance in staging, and that reproduction is what makes the one-minor-version-at-a-time path testable.
Provide a database backup or written permission for the team to take one. Decidim's update guide calls for a database backup before each step, because some minor releases change database structures. Also provide an inventory of everything that sits on top of the core: custom modules, themes, OmniAuth providers, authorization handlers, and integrations with email, maps, storage or external APIs. Each of these can break at a different minor version, so the inventory decides how much regression work each step needs.
Name two people. The first is a business owner who accepts maintenance windows, approves downtime for each step, and signs off the test results on your participatory spaces. The second is a technical owner who receives Decidim security advisories and decides how fast your team will apply them. The grace periods for patching are short, and a missing owner for security advisory response is the gap we see most often. Confirm this owner and a backup contact in writing before the first upgrade is planned.
Finally, supply test accounts with the roles you use (admins, moderators, verified and unverified participants) and written test scenarios for each participatory space and component in use, such as processes, assemblies, meetings, proposals and surveys. Ask us to confirm which scenarios we will run and which your staff will run, because those scripts become the acceptance evidence for each release.
Common questions about Decidim upgrades and support
How much does a Decidim upgrade cost and what drives the price?
Cost follows the written scope, so the figure comes from a quote rather than a general rate. The main drivers are how many minor versions sit between your current release and the target, how much custom code or custom modules must be reviewed and adjusted, how many environments (production, staging, test) need the upgrade, and how much data validation and regression testing you require. Ask for a quote that separates the one-time upgrade work from any recurring support you may want afterward.
How long does a Decidim upgrade take to complete?
Duration depends on the number of minor versions, the amount of custom code, and the number of environments. Decidim's update guide asks you to move one minor version at a time, for example 0.29 to 0.30 before 0.31, and each step has its own instructions, so more steps and more custom code mean more time. No fixed duration applies to every instance. Ask for a timeline in the written scope that lists each version step, the testing stages, and the cutover window.
Can our own team upgrade Decidim without a partner?
Yes, if your team has Ruby on Rails skills and follows the instructions in each release. Each upgrade must be done one minor version at a time, with a database backup taken first, because some releases change database structures. Teams without Rails experience, or with significant custom modules, usually find the review and testing work is the largest part of the effort. Assess your team's skills honestly before deciding.
What happens if we stay on an unsupported Decidim version?
Decidim supports only the last two minor versions with security updates before version 1.0, so the 0.32.x and 0.31.x branches are covered while 0.30.x and earlier are not. An instance on an unsupported branch will not receive security patches from the project, which leaves it exposed to vulnerabilities disclosed after support ends. Plan your upgrade path so you stay within a supported branch, and check the Decidim security policy for the current list.
How do the 2-month and 4-month security grace periods work?
Decidim gives implementers a grace period of 2 months to apply patches for standard vulnerabilities and 4 months for critical ones before the details are disclosed publicly. Your team must be able to deploy patches within those windows, which means keeping a tested upgrade path and a staging environment ready. Confirm with your security team how fast your change process can run, because the grace period only helps if you can apply the patch in time.
Is a Decidim support retainer worth it compared with ad hoc work?
A retainer suits organizations that expect regular releases, patches and monitoring work throughout the year, because it keeps the upgrade path and testing ready. Ad hoc work suits teams with a stable instance, in-house Rails skills and few planned changes. Compare the annual cost of retainer hours against the expected number of incidents and upgrades, and ask for both options in writing with the same scope so the comparison is fair.
How DeployOpen runs Decidim upgrades and support
DeployOpen plans and carries out Decidim upgrades one minor version at a time inside infrastructure you control, then documents the result and supports the instance afterward. Ongoing support is available as a retainer once the work is handed over.
How we scope
- Confirm your current Decidim minor version and the Ruby, Node and PostgreSQL versions your instance runs today.
- Map the upgrade path step by step, since each minor release has its own upgrade instructions and some change database structures.
- Agree in writing which custom modules, themes, login providers and background jobs are in scope, since engagements are fixed-scope.
How we build
- Take a verified backup of the database and file storage before any step, and rehearse each step on a copy of production.
- Work through each minor version in sequence, applying its upgrade instructions and checking custom modules against Ruby and Rails changes.
- Test participant flows, admin tasks, email delivery, maps and social login on staging before each change reaches production.
How we hand over
- Document the final versions, configuration changes, custom module changes and the steps used for each upgrade in the handover pack.
- Record the rollback procedure and the restore test results so your team can reverse a failed step without guesswork.
- Walk your operations team through the runbook, including how to track supported releases and the security patch grace periods.
How we support
- Agree a monitoring and response routine for security advisories, with patches applied within the grace periods Decidim publishes for standard and critical vulnerabilities.
- Plan each new minor release as a scoped upgrade, so your instance stays on one of the two supported minor versions.
- Offer ongoing support as a retainer covering patching, upgrades, backups and incident response, with terms confirmed in the written agreement.
