Add a workflow to generate lua-compatible changelogs (#6444)

.github/workflows/docs-build.yml

@@ -65,12 +65,12 @@ jobs:
         with:
           sparse-checkout: |
             docs
-            .github/workflows/scripts
+            .github/workflows/scripts/bash
 
       # Set environment path for scripts so we can access it later
       - name: Update environment path
         run: |
-          echo "${{ github.workspace }}/.github/workflows/scripts" >> $GITHUB_PATH
+          echo "${{ github.workspace }}/.github/workflows/scripts/bash" >> $GITHUB_PATH
 
       # Retrieve the generated changelogs
       - name: Download artifact changelog of FAF Develop
@@ -90,7 +90,7 @@ jobs:
         run: |
           cat generated/fafdevelop.md >> changelog/fafdevelop.md
           cat generated/fafbeta.md >> changelog/fafbeta.md
-      
+
       # Update the posts directory contents
       - name: Update changelog posts directory
         shell: bash

.github/workflows/docs-changelog.yaml

@@ -48,22 +48,22 @@ on:
 
 jobs:
 
-  # By verifying the snippets we ensure that they're compatible with the bundling  
+  # By verifying the snippets we ensure that they're compatible with the bundling
   # process. In the future we can also add spell checking and/or checks for foul words.
 
   verify:
     name: Verify snippets
     runs-on: ubuntu-latest
     steps:
 
-      # We check out the scripts separate because the branch that we use to 
+      # We check out the scripts separate because the branch that we use to
       # generate the changelog may not contain the scripts that we want to work with.
       - name: Checkout scripts
         uses: actions/checkout@v4
         with:
           path: scripts
           sparse-checkout: |
-            .github/workflows/scripts
+            .github/workflows/scripts/bash
 
       - name: Checkout snippets
         uses: actions/checkout@v4
@@ -76,30 +76,30 @@ jobs:
       - name: Update environment path
         run: |
           ls
-          echo "${{ github.workspace }}/scripts/.github/workflows/scripts" >> $GITHUB_PATH
+          echo "${{ github.workspace }}/scripts/.github/workflows/scripts/bash" >> $GITHUB_PATH
 
       - name: Verify the changelog snippets
         working-directory: fa/changelog/snippets # script assumes it is in this directory
         run: |
           changelog-verify.sh
 
   # During the bundling process we combine the templates, the sections and the snippets
-  # into a single changelog. 
+  # into a single changelog.
 
   bundle:
     name: Bundle snippets
     runs-on: ubuntu-latest
     needs: [verify]
     steps:
 
-      # We check out the scripts separate because the branch that we use to 
+      # We check out the scripts separate because the branch that we use to
       # generate the changelog may not contain the scripts that we want to work with.
       - name: Checkout scripts
         uses: actions/checkout@v4
         with:
           path: scripts
           sparse-checkout: |
-            .github/workflows/scripts
+            .github/workflows/scripts/bash
 
       - name: Checkout snippets
         uses: actions/checkout@v4
@@ -111,7 +111,7 @@ jobs:
 
       - name: Update environment path
         run: |
-          echo "${{ github.workspace }}/scripts/.github/workflows/scripts" >> $GITHUB_PATH
+          echo "${{ github.workspace }}/scripts/.github/workflows/scripts/bash" >> $GITHUB_PATH
 
       # We need to do this to remove `deploy/` from the reference. Specifically the `/` is problematic
       - name: Update reference

.github/workflows/docs-convert-changelog.yaml

@@ -0,0 +1,107 @@
+# Copyright (c) 2024 Daniel 'Zjonn' Dubiel
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+name: Convert Markdown changelog to Lua
+
+on:
+  workflow_dispatch:
+    inputs:
+      reference:
+        required: true
+        type: choice
+        description: The reference (branch or tag) to use to compile the changelog snippets from
+        options:
+          - develop
+          - deploy/fafbeta
+          - deploy/fafdevelop
+
+  workflow_call:
+    inputs:
+      reference:
+        required: true
+        type: string
+        description: The reference (branch or tag) to use to compile the changelog snippets from
+
+jobs:
+  convert_changelog:
+    name: Convert changelog
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set environment variable
+        run: |
+          echo "SCRIPTS=.github/workflows/scripts/python" >> $GITHUB_ENV
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          sparse-checkout: |
+            ${{ env.SCRIPTS }}
+            changelog
+
+      - name: Setup python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.8'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r $SCRIPTS/requirements.txt
+
+      - name: Convert changelog to Lua
+        run: |
+          out_dir=lua_changelog
+          mkdir $out_dir
+          for file in changelog/*.md; do
+            out_file=$(basename ${file%.md}.lua)
+            python3 $SCRIPTS/changelog_markdown2lua.py "${file}" "${out_dir}/${out_file}"
+          done
+
+      - name: Add the Lua changelog as an artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: lua_changelog
+          path: |
+            lua_changelog
+
+  validate_lua_changelog:
+    name: Validate Lua changelog
+    runs-on: ubuntu-latest
+    container: faforever/lua:v5.0-1
+    needs: convert_changelog
+    steps:
+      - name: Install tooling
+        run: |
+          apk add bash git findutils
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          sparse-checkout: |
+            tests/run-syntax-test.sh
+
+      - name: Download the Lua changelog artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: lua_changelog
+
+      - name: Validate changelog files
+        run: |
+          ./tests/run-syntax-test.sh

.github/workflows/scripts/python/README.md

@@ -0,0 +1,31 @@
+# Setting Up Python Environment
+
+This directory contains Python scripts that require specific dependencies to be installed. Follow the instructions below to set up the environment and run the scripts.
+
+## Prerequisites
+
+- At least Python 3.8
+- pip (Python's package installer)
+- python3-venv (Linux only)
+
+
+## Setting Up the Environment
+
+```bash
+# Create a Virtual Environment
+python3 -m venv .venv
+
+# Activate the Virtual Environment
+# On Windows
+.\.venv\Scripts\activate
+# On macOS/Linux
+source .venv/bin/activate
+
+# Install Dependencies
+pip install -r requirements.txt
+
+# Run the script
+python script_name.py
+
+# Deactivate the Virtual Environment
+deactivate

.github/workflows/scripts/python/changelog_markdown2lua.py

@@ -0,0 +1,77 @@
+import mdformat
+
+from argparse import ArgumentParser
+from pathlib import Path
+
+SCRIPT_NAME = Path(__file__).name
+
+MAX_LINE_LENGTH = 150
+
+LUA_DESC_LINE = '        "{line}"'
+LUA_FILE = """Changelog = {{
+    version = {version},
+    description = {{
+{description}
+    }}
+}}
+"""
+
+HEADER_SEPARATOR = "--" * (MAX_LINE_LENGTH // len("--"))
+HEADER_LINE_CENTER = MAX_LINE_LENGTH - 2 * len("--")
+HEADER = f"""{HEADER_SEPARATOR}
+--{f"This file was autogenerated using {SCRIPT_NAME:}":^{HEADER_LINE_CENTER}}--
+--{{source:^{HEADER_LINE_CENTER}}}--
+{HEADER_SEPARATOR}
+
+"""
+
+
+def get_parser():
+    ap = ArgumentParser(description="Converts Markdown release file to Lua.")
+    ap.add_argument(
+        "input_file",
+        help="Markdown file",
+        type=Path,
+    )
+    ap.add_argument(
+        "output_file",
+        help="Lua file",
+        type=Path,
+    )
+    return ap
+
+
+def convert_changelog(markdown: Path, lua: Path):
+    version = markdown.stem
+
+    source_info = f"Source: {markdown}"
+    header = HEADER.format(source=source_info)
+    lua_content = markdown2lua(version, markdown.read_text())
+    lua.write_text(header + lua_content)
+
+
+def markdown2lua(version: str, content: str) -> str:
+    formatted_md = mdformat.text(
+        content,
+        options={
+            "wrap": MAX_LINE_LENGTH,
+        },
+    )
+
+    escaped_md = escape_special_symbols(formatted_md)
+    return LUA_FILE.format(
+        version=version,
+        description=",\n".join(
+            LUA_DESC_LINE.format(line=line) for line in escaped_md.splitlines()
+        ),
+    )
+
+
+def escape_special_symbols(text: str) -> str:
+    return text.replace("\\", "\\\\").replace('"', '\\"')
+
+
+if __name__ == "__main__":
+    parser = get_parser()
+    args = parser.parse_args()
+    convert_changelog(args.input_file, args.output_file)

.github/workflows/scripts/python/requirements.txt

@@ -0,0 +1 @@
+mdformat==0.7.17

.github/workflows/scripts/python/setup_python_env.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+set -euo pipefail
+
+# For debug
+# set -x
+
+VENV_NAME=".venv"
+PYTHON_REQUIREMENTS="requirements.txt"
+SCRIPT_PATH=$(realpath "${BASH_SOURCE[0]}")
+
+SCRIPT_DIR=$(dirname "${SCRIPT_PATH}")
+VENV_PATH="${SCRIPT_DIR}/${VENV_NAME}"
+
+# Check if the user has at least python3.8 (It will reach end-of-life at the end of 2024)
+REQUIRED_VERSION="3.8"
+INSTALLED_VERSION=$(python3 --version 2>&1 | awk '{print $2}')
+
+if [ "$(printf '%s\n' "$REQUIRED_VERSION" "$INSTALLED_VERSION" | sort -V | head -n 1)" != "$REQUIRED_VERSION" ]; then
+    echo "At least python${REQUIRED_VERSION} is required, you have python${INSTALLED_VERSION}"
+    exit 1
+fi
+
+# Check if the script is being sourced
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    echo "Error: This script must be sourced, not executed."
+    echo "Please run: source ${BASH_SOURCE[0]}"
+    exit 2
+fi
+
+# Create venv if it doesn't exist
+if ! [ -f "$VENV_PATH" ]; then
+    python3 -m venv "$VENV_PATH"
+fi
+
+# shellcheck disable=SC1091
+source "${VENV_PATH}/bin/activate"
+
+# Update existing or install missing packages
+python3 -m pip install --upgrade pip
+python3 -m pip install --requirement "${SCRIPT_DIR}/${PYTHON_REQUIREMENTS}"

.gitignore

@@ -22,4 +22,6 @@ textures/ui/common/BUTTON/BACKUP/
 */dds/*
 .idea
 *.DS_Store
-act.exe
+act.exe
+*.venv
+lua_changelog

changelog/snippets/other.6237.md

@@ -0,0 +1 @@
+- (#6237) Convert a markdown-based changelog file into a Lua-based changelog file

changelog/snippets/other.6238.md

@@ -0,0 +1 @@
+- (#6237) Create a Github Workflow to convert markdown changelog files into Lua changelog files