Improve changelog in the release notes (#4179)

This PR adds description to each of the sections of the Changelog part.
Changes are based on feedback that it wasn't that clear what exactly
`Node Dev`, `Runtime Dev` etc. means. Now, the description for each of
those parts is taken directly from the `prdoc` schema.
Closes https://github.com/paritytech/release-engineering/issues/197

.github/workflows/release-30_publish_release_draft.yml

@@ -42,7 +42,6 @@ jobs:
           URL=https://github.com/chevdor/tera-cli/releases/download/v0.2.4/tera-cli_linux_amd64.deb
           wget $URL -O tera.deb
           sudo dpkg -i tera.deb
-          tera --version
 
       - name: Download artifacts
         uses: actions/download-artifact@c850b930e6ba138125429b7e5c93fc707a7f8427 # v4.1.4
@@ -70,7 +69,7 @@ jobs:
 
           export REF1=$(get_latest_release_tag)
           if [[ -z "${{ inputs.version }}" ]]; then
-            export REF2="${{ github.ref }}"
+            export REF2="${{ github.ref_name }}"
           else
             export REF2="${{ inputs.version }}"
           fi
@@ -79,10 +78,6 @@ jobs:
 
           ./scripts/release/build-changelogs.sh
 
-          echo "Checking the folder state"
-          pwd
-          ls -la scripts/release
-
       - name: Archive artifact context.json
         uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1
         with:
@@ -151,5 +146,5 @@ jobs:
           access_token: ${{ secrets.RELEASENOTES_MATRIX_V2_ACCESS_TOKEN }}
           server: m.parity.io
           message: |
-            **New version of polkadot tagged**: ${{ github.ref }}<br/>
+            **New version of polkadot tagged**: ${{ github.ref_name }}<br/>
             Draft release created: ${{ needs.publish-release-draft.outputs.release_url }}

scripts/release/build-changelogs.sh

@@ -2,11 +2,10 @@
 
 export PRODUCT=polkadot
 export VERSION=${VERSION:-1.5.0}
-export ENGINE=${ENGINE:-docker}
+export ENGINE=${ENGINE:-podman}
 export REF1=${REF1:-'HEAD'}
 export REF2=${REF2}
 export RUSTC_STABLE=${RUSTC_STABLE:-'1.0'}
-export RUSTC_NIGHTLY=${RUSTC_NIGHTLY:-'1.0'}
 
 PROJECT_ROOT=`git rev-parse --show-toplevel`
 echo $PROJECT_ROOT
@@ -27,35 +26,43 @@ echo -e "OUTPUT: \t\t$OUTPUT"
 mkdir -p $OUTPUT
 
 $ENGINE run --rm -v ${PROJECT_ROOT}:/repo paritytech/prdoc load -d "prdoc/$VERSION" --json > $DATA_JSON
-# ls -al $DATA_JSON
 
 cat $DATA_JSON | jq ' { "prdoc" : .}' > $CONTEXT_JSON
-# ls -al $CONTEXT_JSON
 
-# Fetch the list of valid audiences
+# Fetch the list of valid audiences and their descriptions
 SCHEMA_URL=https://raw.githubusercontent.com/paritytech/polkadot-sdk/master/prdoc/schema_user.json
 SCHEMA=$(curl -s $SCHEMA_URL | sed 's|^//.*||')
-AUDIENCE_ARRAY=$(echo -E $SCHEMA | jq -r '."$defs".audience.oneOf[] | .const')
-
-readarray -t audiences < <(echo "$AUDIENCE_ARRAY")
-declare -p audiences
-
-
-# Generate a changelog
-echo "Generating changelog..."
-tera -t "${TEMPLATE_CHANGELOG}" --env --env-key env "${CONTEXT_JSON}" > "$OUTPUT/changelog.md"
-echo "Changelog ready in $OUTPUT/changelog.md"
+aud_desc_array=()
+while IFS= read -r line; do
+    audience=$(jq -r '.const' <<< "$line" )
+    description=$(jq -r '.description' <<< "$line")
+    if [ -n "$audience" ] && [ -n "$description" ]; then
+        aud_desc_array+=("($audience; $description)")
+    fi
+done < <(jq -c '."$defs".audience_id.oneOf[]' <<< "$SCHEMA")
 
 # Generate a release notes doc per audience
-for audience in "${audiences[@]}"; do
+for tuple in "${aud_desc_array[@]}"; do
+    audience=$(echo "$tuple" | cut -d ';' -f 1 | sed 's/(//')
     audience_id="$(tr [A-Z] [a-z] <<< "$audience")"
     audience_id="$(tr ' ' '_' <<< "$audience_id")"
+
+    description=$(echo "$tuple" | cut -d ';' -f 2 | sed 's/)//')
+
     echo "Processing audience: $audience ($audience_id)"
-    export TARGET_AUDIENCE=$audience
+    export TARGET_AUDIENCE="$audience"
+    export AUDIENCE_DESC="**These changes are relevant to:** $description"
+
     tera -t "${TEMPLATE_AUDIENCE}" --env --env-key env "${CONTEXT_JSON}" > "$OUTPUT/relnote_${audience_id}.md"
     cat "$OUTPUT/relnote_${audience_id}.md" >> "$PROJECT_ROOT/scripts/release/templates/changelog.md"
 done
 
+
+# Generate a changelog containing list of the commits
+echo "Generating changelog..."
+tera -t "${TEMPLATE_CHANGELOG}" --env --env-key env "${CONTEXT_JSON}" > "$OUTPUT/relnote_commits.md"
+echo "Changelog ready in $OUTPUT/relnote_commits.md"
+
 # Show the files
 tree -s -h -c $OUTPUT/
 

scripts/release/templates/audience.md.tera

@@ -1,5 +1,7 @@
 ### Changelog for `{{ env.TARGET_AUDIENCE }}`
 
+{{ env.AUDIENCE_DESC }}
+
 {% for file in prdoc -%}
 {% for doc_item in file.content.doc %}
 {%- if doc_item.audience == env.TARGET_AUDIENCE %}