Automate changelog and release packs for randomizer (#70)

.github/pull_request_template.md

@@ -0,0 +1,5 @@
+<!--
+If making a change in the Entrance Randomizer, remember to add a changelog entry.
+For for more information, read:
+https://github.com/Avasam/ptle-tools/blob/main/Dolphin%20scripts/Entrance%20Randomizer/CHANGELOG.md
+-->

.github/verify_newsfragments.py

@@ -0,0 +1,29 @@
+import re
+import sys
+from os import listdir
+from pathlib import Path
+
+NEWS_TYPES = ("feature", "bugfix", "doc", "removal", "misc")
+
+NEWS_PATTERN = re.compile(r"(\d+|\+.+)\.(" + "|".join(NEWS_TYPES) + r")\.md")
+
+NEWSFRAGMENTS_FIR = Path(__file__).parent.parent / "Dolphin scripts" / \
+    "Entrance Randomizer" / "newsfragments"
+
+
+def main():
+    invalid_filenames = [
+        filename for filename
+        in listdir(NEWSFRAGMENTS_FIR)
+        if not NEWS_PATTERN.fullmatch(filename)
+    ]
+
+    if invalid_filenames:
+        sys.exit(
+            "The following newsfragments don't match the "
+            + f"{NEWS_PATTERN} pattern: {invalid_filenames}",
+        )
+
+
+if __name__ == "__main__":
+    main()

.github/workflows/pack-randomizer-release.yaml

@@ -0,0 +1,46 @@
+name: Pack Randomizer (Release)
+
+on:
+  workflow_dispatch: #  Allows manual triggers
+  push:
+    branches:
+      - main
+    paths:
+      # Release trigger
+      - "Dolphin scripts/Entrance Randomizer/CHANGELOG.md"
+  pull_request:
+    branches:
+      - main
+    paths:
+      # Release tooling
+      - "Dolphin scripts/pack-rando.ps1"
+      - ".github/workflows/pack-randomizer-release.yaml"
+
+env:
+  PIP_DISABLE_PIP_VERSION_CHECK: 1
+  FORCE_COLOR: 1
+
+jobs:
+  pack-randomizer:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: '& "Dolphin scripts/pack-rando.ps1" -Release'
+        shell: pwsh
+      # upload-artifact will double zip, so unpack first
+      # https://github.com/actions/upload-artifact/issues/39
+      - name: Get pack filename
+        id: packname
+        run: |
+          echo "packname=$(
+            find -name 'Entrance Randomizer v*.zip' | sed 's/\.zip$//1' | sed 's/^\.\///1'
+          )" >> $GITHUB_OUTPUT
+      - name: Extract premade archive
+        run: |
+          7z x \
+          '${{ steps.packname.outputs.packname }}.zip' \
+          -o'${{ steps.packname.outputs.packname }}'
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ${{ steps.packname.outputs.packname }}
+          path: ${{ steps.packname.outputs.packname }}/*

.github/workflows/typecheck.yaml → .github/workflows/tests.yaml

@@ -1,4 +1,4 @@
-name: Typecheck
+name: Tests
 
 on:
   workflow_dispatch: #  Allows manual triggers
@@ -41,3 +41,13 @@ jobs:
       - uses: jakebailey/pyright-action@v2
         with:
           version: ${{ steps.pyright_version.outputs.PYRIGHT_VERSION }}
+
+  verify_newsfragments:
+    name: Verify Newsfragments
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: python .github/verify_newsfragments.py
+      - run: python -m pip install towncrier
+      # - run: python -m towncrier check
+      - run: python -m towncrier build --draft --version check

Dolphin scripts/Entrance Randomizer/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to the Entrance Randomizer will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). The version semantics are inspired by [Semantic Versioning](https://semver.org/spec/v2.0.0.html). and go as follow:
+
+```txt
+Major.Minor.Patch
+
+Major: New major feature or functionality (stays 0 until the first "stable" release)
+Minor: Affects seed
+Patch: Does't affect seed (assuming same settings)
+```
+
+This project uses [*towncrier*](https://towncrier.readthedocs.io/) and the changes for the upcoming release can be found in <https://github.com/Avasam/ptle-tools/blob/main/Dolphin%20scripts/Entrance%20Randomizer/newsfragments>.
+
+To add a changelog entry, add a new file `<issue_or_pr_#>.<type>.md` to the `newsfragments` folder.
+(See the different [fragment types](https://towncrier.readthedocs.io/en/latest/tutorial.html#creating-news-fragments))
+
+<!-- towncrier release notes start -->
+
+## 5.0.0 - 2024-07-13

Dolphin scripts/Entrance Randomizer/lib/constants.py

@@ -11,13 +11,7 @@
 from lib.transition_infos import transition_infos
 
 __version = "0.4.0"
-"""
-Major: New major feature or functionality
-
-Minor: Affects seed
-
-Patch: Does't affect seed (assuming same settings)
-"""
+"""See CHANGELOG.md for version semantics."""
 __dev_version = "local"
 __version__ = f"{__version}-{__dev_version}"
 print(f"Python version: {sys.version}")

Dolphin scripts/Entrance Randomizer/newsfragments/70.doc.md

@@ -0,0 +1 @@
+Initialized the changelog using Towncrier -- by @Avasam

Dolphin scripts/README.md

@@ -34,9 +34,12 @@ Shaman Shop:
 1. Use this fork of Dolphin <https://github.com/Felk/dolphin/releases>.
 2. Turn on "Scripting" logs and set Verbosity to "Error" or any option below (not "Notice").
 3. Download the randomizer zip file, either:
-    - from Discord;
-    - zip it yourself using `pack-rando.ps1`;
-    - download an unreleased [development build](https://github.com/Avasam/ptle-tools/actions/workflows/pack-randomizer.yaml?query=branch%3Amain+is%3Asuccess) (requires a GitHub account);
+    - latest release:
+      - from [#randomizer](https://discord.com/channels/334793217138622464/1083867986068254760) channel on Discord;
+      - [release artefacts](https://github.com/Avasam/ptle-tools/actions/workflows/pack-randomizer-release.yaml?query=branch%3Amain+is%3Asuccess+event%3Apush) (requires a GitHub account);
+    - development build:
+      - zip it yourself using `pack-rando.ps1`;
+      - [development builds](https://github.com/Avasam/ptle-tools/actions/workflows/pack-randomizer.yaml?query=branch%3Amain+is%3Asuccess+event%3Apush) (requires a GitHub account);
 4. Open this zip file and drop "Scripts" at the root of your Dolphin installation (the location and names are important!).
 5. Configurations are found in `Scripts/Entrance Randomizer/CONFIGS.py`.
 6. In Dolphin, under "Scripts", click "Add new Scripts" and select `Scripts/Entrance Randomizer/__main__.py`.
@@ -73,3 +76,12 @@ In order to display the generated map take these steps:
 3. Clone this repository.
 4. Run `symlink-scripts.ps1 "<path to dolphin-scripting>"`.
 5. In Dolphin, under "Scripts", click "Add new Scripts" and select `Scripts/Entrance Randomizer/__main__.py`.
+
+#### Creating a release
+
+This section serves as a reminder for myself. To create a new release:
+
+1. Run [version-bump.ps1](/Dolphin%20scripts/version-bump.ps1).
+2. Push to `main`. Any change to `CHANGELOG.md` should trigger a release pack.
+3. Share on Discord with a link to the latest release section.
+4. Unpin old version message, pin new version message.

Dolphin scripts/pack-rando.ps1

@@ -1,3 +1,7 @@
+param (
+  [switch] $Release = $False
+)
+
 $ScriptsFolder = "$PSScriptRoot\Scripts"
 $RandoFolderName = 'Entrance Randomizer'
 $VersionFilePath = "$ScriptsFolder\$RandoFolderName/lib/constants.py"
@@ -8,7 +12,12 @@ Copy-Item -Path "$PSScriptRoot\..\Various technical notes\transition_infos.json"
 $VersionFileContent = Get-Content $VersionFilePath
 $VersionLine = $VersionFileContent | Select-String -Pattern '^__version\s*=\s*".*"'
 $RandoVersion = $VersionLine -replace '^\s*__version\s*=\s*"', '' -replace '".*$', ''
-$DevVersion = git rev-parse --short HEAD
+if ($Release) {
+  $DevVersion = ''
+}
+else {
+  $DevVersion = git rev-parse --short HEAD
+}
 $VersionFileContent -replace '^\s*__dev_version.*', "__dev_version = `"$DevVersion`"" | Set-Content $VersionFilePath
 
 Compress-Archive -Path $ScriptsFolder -DestinationPath "$RandoFolderName v$RandoVersion-$DevVersion.zip" -Force

Dolphin scripts/version-bump.ps1

@@ -0,0 +1,8 @@
+$RandoFolderName = 'Entrance Randomizer'
+$VersionFilePath = "$PSScriptRoot\$RandoFolderName/lib/constants.py"
+
+$RandoVersion = Read-Host 'Version number (X.X.X)'
+$VersionFileContent = Get-Content $VersionFilePath
+$VersionFileContent -replace '^\s*__version = .*', "__version = `"$RandoVersion`"" | Set-Content $VersionFilePath
+
+towncrier build --draft --version $RandoVersion

pyproject.toml

@@ -193,3 +193,15 @@ reportUnnecessaryComparison = "warning"
 # Too strict
 reportMissingSuperCall = "none"
 reportUnusedCallResult = "none"
+
+# Once we have multiple changelogs to maintain, see
+# https://towncrier.readthedocs.io/en/latest/monorepo.html
+[tool.towncrier]
+directory = "Dolphin scripts/Entrance Randomizer/newsfragments"
+filename = "Dolphin scripts/Entrance Randomizer/CHANGELOG.md"
+issue_format = "[#{issue}](https://github.com/Avasam/ptle-tools/issues/{issue})"
+package = "Entrance Randomizer"
+package_dir = "Dolphin scripts"
+start_string = "<!-- towncrier release notes start -->\n"
+title_format = "## {version} - {project_date}"
+underlines = ["", "", ""]