Modifying CiviCRM core message templates

Make it easy to diff at next upgrade

Background

Consider this problem:

• Your modification is presumably based on the current CiviCRM version's ("Version X") default template.
• At any future upgrade, CiviCRM may modify that default template.
• Future upgrades may require you to update your template (deprecated tokens, new template logic, etc.)
• If know what "Version X" was, you can easily diff your modified template against that original template.
• But if you don't know, it can be very hard to identify your changes within the modified template.

Also consider:

• CiviCRM core files are the defining source of default message templates for each version.
• However, whitespace is different when comparing core file with the UI-displayed "default template" content.
• Diffing is easier when comparing to a consistent base.
• The core files in their raw form (e.g. https://raw.githubusercontent.com/civicrm/civicrm-core/refs/tags/6.16.4/xml/templates/message_templates/contribution_offline_receipt_html.tpl) are that consistent base.

Policy

When editing a core message template:

• Do not start from the UI-provided content. Start from the core file in its raw form: https://raw.githubusercontent.com/civicrm/civicrm-core/refs/tags/[Version_X]/xml/templates/message_templates/[workflow_name]_html.tpl
• Always add (or update) a Smarty comment in the very first line, like so:
  {* Modified from: https://raw.githubusercontent.com/civicrm/civicrm-core/refs/tags/[Version_X]/xml/templates/message_templates/[workflow_name]_html.tpl *}
  e.g.
  {* Modified from: https://raw.githubusercontent.com/civicrm/civicrm-core/refs/tags/6.16.4/xml/templates/message_templates/contribution_offline_receipt_html.tpl *}
• If you're not sure of the value for [workflow_name] (it's not easy to tell from the web UI), use the message_template_id (which is in the UI, at least in the URL) and an api call like so:

    # Assuming message_template_id=5
    cv api MessageTemplate.get sequential=1 return="workflow_name" id=5 
    {
        "is_error": 0,
        "version": 3,
        "count": 1,
        "id": 5,
        "values": [
            {
                "id": "5",
                "workflow_name": "contribution_offline_receipt"
            }
        ]
    }
  

When diffing a modified template to identify its changes - Compare against the consistent base, which is the core file, e.g. https://raw.githubusercontent.com/civicrm/civicrm-core/refs/tags/6.16.4/xml/templates/message_templates/contribution_invoice_receipt_html.tpl - Don't compare against the UI-provided "default message template" contents.