Update upgrade documentation for DefectDojo Version 2.58.x to clarify notification .tpl templates relocation

Author: Maffooch

docs/content/releases/os_upgrading/2.58.md

@@ -2,33 +2,27 @@
 title: 'Upgrading to DefectDojo Version 2.58.x'
 toc_hide: true
 weight: -20260504
-description: Notification templates relocated under dojo/notifications/
+description: Notification .tpl templates relocated under dojo/notifications/
 ---
 
-## Notification templates relocated
+## Notification `.tpl` templates relocated
 
-The notification domain has been consolidated under a new `dojo/notifications/` package. Notification templates that previously lived under `dojo/templates/` have been moved into `dojo/notifications/templates/notifications/`. Most templates can still be resolved by their existing lookup name, but the seven notification UI templates have been re-namespaced and any custom overrides of those need to be updated.
+The notification domain has been consolidated under a new `dojo/notifications/` package, and the 62 channel `.tpl` templates that drive alert, mail, MS Teams, Slack, and webhook notifications have moved on disk. The Django template lookup name (e.g. `notifications/mail/scan_added.tpl`) is unchanged, so most customizations keep working without any edits — but operators who override `.tpl` files by mounting them into the source tree need to update their paths.
 
-### Channel templates (no action required for most users)
+### What moved
 
-The 62 channel templates under `alert/`, `mail/`, `msteams/`, `slack/`, `webhooks/`, and `webhooks_summary/` keep their existing template lookup names (e.g. `notifications/mail/scan_added.tpl`, `notifications/slack/sla_breach.tpl`). Existing customizations that override these by lookup name continue to work — only the on-disk source location has changed.
+The channel templates under `alert/`, `mail/`, `msteams/`, `slack/`, `webhooks/`, and `webhooks_summary/` have been relocated:
 
-### Notification UI templates (action required if customized)
-
-The seven notification UI templates have moved AND been re-namespaced from `dojo/...html` to `notifications/...html`:
-
-| Old lookup name | New lookup name |
+| Old on-disk location | New on-disk location |
 | --- | --- |
-| `dojo/alerts.html` | `notifications/alerts.html` |
-| `dojo/delete_alerts.html` | `notifications/delete_alerts.html` |
-| `dojo/notifications.html` | `notifications/notifications.html` |
-| `dojo/add_notification_webhook.html` | `notifications/add_notification_webhook.html` |
-| `dojo/edit_notification_webhook.html` | `notifications/edit_notification_webhook.html` |
-| `dojo/delete_notification_webhook.html` | `notifications/delete_notification_webhook.html` |
-| `dojo/view_notification_webhooks.html` | `notifications/view_notification_webhooks.html` |
+| `dojo/templates/notifications/{channel}/{event}.tpl` | `dojo/notifications/templates/notifications/{channel}/{event}.tpl` |
+
+For example, `dojo/templates/notifications/mail/scan_added.tpl` now lives at `dojo/notifications/templates/notifications/mail/scan_added.tpl`. A new `TEMPLATES["DIRS"]` entry pointing at `dojo/notifications/templates/` is registered automatically, so the lookup path used by `render_to_string()` (e.g. `notifications/slack/sla_breach.tpl`) resolves exactly as before.
 
-### Required Actions
+### Required actions
 
-If you have overridden any of the seven notification UI templates above (for example by placing a custom `dojo/notifications.html` in your own templates directory), you must rename the override to the new `notifications/...html` path so it continues to take effect. No action is required for users who have not customized these templates, and no action is required for the channel `.tpl` templates regardless of customization.
+- **Customizing `.tpl` files via your own templates directory (recommended pattern):** No action required. Overrides resolved by lookup name continue to take precedence.
+- **Customizing `.tpl` files via a Docker volume mount or in-tree patch at the old `dojo/templates/notifications/...` path:** Update the mount/patch target to the new `dojo/notifications/templates/notifications/...` path, or move your override into a project-level templates directory keyed by the lookup name.
+- **No customizations:** No action required.
 
 For more information, check the [Release Notes](https://github.com/DefectDojo/django-DefectDojo/releases/tag/2.58.0).