What this template is for
Dependency upgrades are how teams accumulate or shed technical debt. Routine patch bumps are mostly automated; non-trivial upgrades (major versions, runtime changes, framework migrations) are where teams either invest in careful testing or accumulate outages and security debt.
This template is for the non-trivial category:
- Required fields on the create screen - current version, target version, upgrade reason, breaking changes, affected components, test coverage, rollout strategy, rollback plan. The rollout-strategy and rollback-plan fields force the team to plan the operational side before any code is written.
- STM-created sub-tasks - review breaking changes, identify affected components, apply, test, regression-test, stage, roll out, monitor. The staging observation and rollout sub-tasks are the ones that fail most often when teams skip them under deadline pressure.
When to use it
Use this template for major version bumps, runtime upgrades (Java, Node, Python), framework upgrades (Spring, Django, React major versions), database driver upgrades, and any security-driven upgrade with breaking changes.
For routine patch-version bumps handled by Dependabot or Renovate, the bot’s PR is sufficient documentation - no need to file a Jira ticket. Use this template specifically when the upgrade requires thought beyond ‘merge the bot’s PR’.
Fields to add to your Jira create screen
These are the fields a project admin should make sure exist on the Create Issue screen for this issue type (Project settings → Screens). Without these on the screen, reporters can't provide the information triage needs - and STM can't reference them either.
| Field | Example value | Required |
|---|---|---|
Summary | Upgrade Postgres driver from 42.x to 43.x | Yes |
Dependency Name | org.postgresql:postgresql | Yes |
Current Version | 42.7.3 | Yes |
Target Version | 43.1.0 | Yes |
Upgrade Reason (custom) | Security CVE / End-of-life / New required feature / Routine | Yes |
Breaking Changes (custom) | Summary of breaking changes from the release notes | Yes |
Affected Components | Which services use this dependency | Yes |
Test Coverage (custom) | What tests will validate the upgrade - unit, integration, load | Yes |
Rollout Strategy (custom) | All at once / Canary / Per-service - and why | Yes |
Rollback Plan (custom) | Specific steps to revert the upgrade if needed | Yes |
Security CVE Reference (if applicable) | CVE-2026-12345 - links security driver to this work | No |
Note on custom fields. STM currently supports up to 5 custom fields per template. You can add as many custom fields as you like to your Jira Create Issue screen - the 5-field limit only applies if you want STM to set or update those custom fields itself.
Sub-tasks STM creates automatically
Build an STM sub-task template containing the items below, then wire it to an On Create Issue Executor scoped to this issue type. Whenever a new issue of this type is created in the project, STM creates the full sub-task set in one step - with assignee, due date, and components inherited from the parent unless you override them.
- Review breaking changes in the dependency release notes
- Identify affected components and services
- Apply the upgrade in a branch / dev environment
- Run unit + integration tests; investigate any new failures
- Run targeted regression tests on most-affected code paths
- Deploy to staging and observe for at least 24 hours
- Roll out per rollout strategy (canary, per-service, etc.)
- Monitor for issues post-deploy - have rollback ready
Common questions
What's the difference between a routine dependency upgrade and a non-trivial one?
Routine: patch-version upgrade with no breaking changes, no schema changes, no migration steps. Non-trivial: major version upgrade, runtime change, framework upgrade, anything with breaking changes or migration steps. Routine upgrades can be handled by Dependabot/Renovate PRs; non-trivial upgrades need this template because the test coverage and rollback plan need explicit thought.
Should security-driven dependency upgrades follow the same template as routine ones?
Use the security-finding template for the vulnerability itself (with the CVE), and link this dependency-upgrade ticket to it as the remediation. The security-finding ticket tracks the SLA and customer notification; the dependency-upgrade ticket tracks the actual technical work. Don't conflate the two - they have different audit requirements.
How do you handle dependency upgrades that affect multiple services?
One ticket per service, linked to a parent epic for the upgrade campaign. Each service has different test coverage and rollout requirements. Cross-service upgrades that try to fit on a single ticket lose track of which services are upgraded, which are pending, and which had problems.
What goes in the test coverage field for a Jira dependency upgrade?
Specific test suites and what they validate. 'Run existing tests' is not test coverage - the existing tests passed on the OLD version, that's why you're upgrading. New tests, or explicit re-runs of integration / load / smoke tests against the new version, are what build confidence. Document them on the ticket so the upgrade is reproducible.
Automate the sub-tasks with STM
STM Issue Templates saves the sub-task list above as a reusable template and creates them on every new issue of this type - via an Executor on issue creation, on status transition, or triggered manually from the issue's "Create bulk sub-tasks" menu. STM does not change the parent issue's create screen (that's a Jira project-settings job) but it removes the manual work of creating the sub-tasks every time.
Try STM on the Atlassian Marketplace ↗ See how STM templates are built →