From 42ceb1c1b1a4a1be2c10898be72b191abf0e7622 Mon Sep 17 00:00:00 2001
From: Chevdor <chevdor@users.noreply.github.com>
Date: Wed, 11 May 2022 11:20:34 +0200
Subject: [PATCH] Release notes fixes (#5494)

* Move compiler information below priority information

* Show docker section by default

* Show a mention even if there are no host functions

* Fix the wording for the migrations

* Fix some wording

* Include free notes section

* Fix spacing issue

* Rename the free notes template

* Few minor changes including reworking the tag rendering
---
 .../ci/changelog/templates/_free_notes.md.tera       | 10 ++++++++++
 .../scripts/ci/changelog/templates/compiler.md.tera  |  3 ++-
 .../scripts/ci/changelog/templates/debug.md.tera     |  2 --
 .../ci/changelog/templates/docker_image.md.tera      |  6 +++---
 .../ci/changelog/templates/host_functions.md.tera    | 10 +++++-----
 .../ci/changelog/templates/migrations-db.md.tera     |  4 ++--
 .../changelog/templates/migrations-runtime.md.tera   |  4 ++--
 .../ci/changelog/templates/pre_release.md.tera       |  2 +-
 .../scripts/ci/changelog/templates/template.md.tera  | 12 +++++++++---
 9 files changed, 34 insertions(+), 19 deletions(-)
 create mode 100644 polkadot/scripts/ci/changelog/templates/_free_notes.md.tera

diff --git a/polkadot/scripts/ci/changelog/templates/_free_notes.md.tera b/polkadot/scripts/ci/changelog/templates/_free_notes.md.tera
new file mode 100644
index 00000000000..c4a841a9925
--- /dev/null
+++ b/polkadot/scripts/ci/changelog/templates/_free_notes.md.tera
@@ -0,0 +1,10 @@
+
+{# This file uses the Markdown format with additional templating such as this comment. -#}
+{# Such a comment will not show up in the rendered release notes. -#}
+{# The content of this file (if any) will be inserted at the top of the release notes -#}
+{# and generated for each new release candidate. -#}
+{# Ensure you leave an empty line at both top and bottom of this file. -#}
+
+<!-- Such a comment will be rendered but remain invisible in the rendered markdown -->
+<!-- Edit below this line -->
+<!-- Edit above this line -->
diff --git a/polkadot/scripts/ci/changelog/templates/compiler.md.tera b/polkadot/scripts/ci/changelog/templates/compiler.md.tera
index 0420a88c396..6fa1baa6506 100644
--- a/polkadot/scripts/ci/changelog/templates/compiler.md.tera
+++ b/polkadot/scripts/ci/changelog/templates/compiler.md.tera
@@ -1,6 +1,7 @@
 ## Rust compiler versions
 
-This release was tested against the following versions of `rustc`. Other versions may work.
+This release was built and tested against the following versions of `rustc`.
+Other versions may work.
 
 - Rust Stable: `{{ env.RUSTC_STABLE }}`
 - Rust Nightly: `{{ env.RUSTC_NIGHTLY }}`
diff --git a/polkadot/scripts/ci/changelog/templates/debug.md.tera b/polkadot/scripts/ci/changelog/templates/debug.md.tera
index 29ac673a394..41f3702d7c0 100644
--- a/polkadot/scripts/ci/changelog/templates/debug.md.tera
+++ b/polkadot/scripts/ci/changelog/templates/debug.md.tera
@@ -1,8 +1,6 @@
 {%- set to_ignore = changes | filter(attribute="meta.B.value", value=0) %}
 
 <!--
-## Debug
-
 changes:
  - total: {{ changes | length }}
  - silent: {{ to_ignore | length }}
diff --git a/polkadot/scripts/ci/changelog/templates/docker_image.md.tera b/polkadot/scripts/ci/changelog/templates/docker_image.md.tera
index 59f631106b5..5311f18a18a 100644
--- a/polkadot/scripts/ci/changelog/templates/docker_image.md.tera
+++ b/polkadot/scripts/ci/changelog/templates/docker_image.md.tera
@@ -1,11 +1,11 @@
-<!--
+
 ## Docker images
 
-The docker image for this release can be found in [Docker hub](https://hub.docker.com/r/parity/polkadot-collator/tags?page=1&ordering=last_updated).
+The docker image for this release can be found in [Docker hub](https://hub.docker.com/r/parity/polkadot-collator/tags?page=1&ordering=last_updated)
+(It will be available a few minutes after this release was published).
 
 You may also pull it with:
 
 ```
 docker pull parity/polkadot-collator:latest
 ```
--->
diff --git a/polkadot/scripts/ci/changelog/templates/host_functions.md.tera b/polkadot/scripts/ci/changelog/templates/host_functions.md.tera
index 9f954078da2..46efc8cae92 100644
--- a/polkadot/scripts/ci/changelog/templates/host_functions.md.tera
+++ b/polkadot/scripts/ci/changelog/templates/host_functions.md.tera
@@ -15,16 +15,16 @@
 
 <!-- {{ host_fn_count }} host functions were detected -->
 
-{%- if host_fn_count == 0 -%}
-<!-- ℹ️ This release does not contain any new host functions. -->
-{% elif host_fn_count == 1 -%}
 ## Host functions
 
+{%- if host_fn_count == 0 %}
+ℹ️ This release does not contain any new host functions.
+{% elif host_fn_count == 1 -%}
 ⚠️ The runtimes in this release contain one new **host function**.
 
-⚠️ It is critical that you update your client before the chain switches to the new runtimes.
+⚠️ It is critical that you update your client before the chain switches to the new runtime.
 {%- else -%}
 ⚠️ The runtimes in this release contain {{ host_fn_count }} new **host function{{ host_fn_count | pluralize }}**.
 
-⚠️ It is critical that you update your client before the chain switches to the new runtimes.
+⚠️ It is critical that you update your client before the chain switches to the new runtime.
 {%- endif %}
diff --git a/polkadot/scripts/ci/changelog/templates/migrations-db.md.tera b/polkadot/scripts/ci/changelog/templates/migrations-db.md.tera
index d2fd8105e41..02fbbf89d18 100644
--- a/polkadot/scripts/ci/changelog/templates/migrations-db.md.tera
+++ b/polkadot/scripts/ci/changelog/templates/migrations-db.md.tera
@@ -16,10 +16,10 @@
 {% endfor -%}
 
 {%- if db_migration_count == 0 -%}
-No Database migration detected in this release.
+ℹ️ There is no database migration in this release.
 {% else  %}
 
-There is {{ db_migration_count }} database migration(s) in this release.
+⚠️ There is {{ db_migration_count }} database migration(s) in this release.
 
 Database migrations are operations bringing your database to the latest stand.
 Some migrations may break compatibility and making a backup of your database is highly recommended.
diff --git a/polkadot/scripts/ci/changelog/templates/migrations-runtime.md.tera b/polkadot/scripts/ci/changelog/templates/migrations-runtime.md.tera
index 36529e0d21e..4d357598cff 100644
--- a/polkadot/scripts/ci/changelog/templates/migrations-runtime.md.tera
+++ b/polkadot/scripts/ci/changelog/templates/migrations-runtime.md.tera
@@ -16,10 +16,10 @@
 {% endfor -%}
 
 {%- if runtime_migration_count == 0 -%}
-No Runtime migration detected in this release.
+ℹ️ There is no runtime migration in this release.
 {% else  %}
 
-There is {{ runtime_migration_count }} runtime migration(s) in this release.
+⚠️ There is {{ runtime_migration_count }} runtime migration(s) in this release.
 
 Runtime migrations are operations running once during a runtime upgrade.
 {%- endif %}
diff --git a/polkadot/scripts/ci/changelog/templates/pre_release.md.tera b/polkadot/scripts/ci/changelog/templates/pre_release.md.tera
index 53a0e906541..cb242e90310 100644
--- a/polkadot/scripts/ci/changelog/templates/pre_release.md.tera
+++ b/polkadot/scripts/ci/changelog/templates/pre_release.md.tera
@@ -4,7 +4,7 @@
 **Release candidates** are **pre-releases** may not be final.
 Although they are reasonably tested, there may be additional changes or issues
 before an official release is tagged. Use at your own discretion, and consider
-only using published releases on critical production infrastructure.
+only using final releases on critical production infrastructure.
 </details>
 {% else -%}
 <!-- NOT a pre-release-->
diff --git a/polkadot/scripts/ci/changelog/templates/template.md.tera b/polkadot/scripts/ci/changelog/templates/template.md.tera
index e6e800fd9c7..42d0c9f5703 100644
--- a/polkadot/scripts/ci/changelog/templates/template.md.tera
+++ b/polkadot/scripts/ci/changelog/templates/template.md.tera
@@ -3,7 +3,7 @@
 {% include "pre_release.md.tera" -%}
 
 {% if env.PRE_RELEASE == "true" -%}
-This pre-release contains the changes from `{{ env.REF1 }}` to `{{ env.REF2 }}`.
+This pre-release contains the changes from `{{ env.REF1 | replace(from="refs/tags/", to="") }}` to `{{ env.REF2 | replace(from="refs/tags/", to="") }}`.
 {%- else -%}
 This release contains the changes from `{{ env.REF1 }}` to `{{ env.REF2 }}`.
 {% endif -%}
@@ -15,15 +15,21 @@ This release contains the changes from `{{ env.REF1 }}` to `{{ env.REF2 }}`.
 {%- set DOT = "[P]" -%}
 {%- set SUB = "[S]" -%}
 
+{# -- Manual free notes section -- #}
+{% include "_free_notes.md.tera" -%}
+{# --------------------------------- #}
+
+{# -- Important automatic section -- #}
 {% include "global_priority.md.tera" -%}
 
 {% include "host_functions.md.tera" -%}
 
-{% include "compiler.md.tera" -%}
-
 {% include "migrations-db.md.tera" -%}
 
 {% include "migrations-runtime.md.tera" -%}
+{# --------------------------------- #}
+
+{% include "compiler.md.tera" -%}
 
 {% include "runtimes.md.tera" -%}
 
-- 
GitLab