reworked build & release procedure + repository cleanup

Author: agurtovoy

.github/HOWTO.md

@@ -1,5 +1,6 @@
 You can test GitHub Actions workflows locally using [`act`](https://nektosact.com/) and [Docker](https://www.docker.com/):
 
 ```shell
-act --container-architecture linux/amd64
+act --container-architecture linux/amd64 -W '.github/workflows/prepare-release-pr.yml'
+act --container-architecture linux/amd64 -W '.github/workflows/release.yml'
 ```

.github/workflows/prepare-release-pr.yml

@@ -13,7 +13,8 @@ jobs:
   prepare-release-pr:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - name: Check out sources
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0 # Need full history for changelog
 
@@ -50,11 +51,11 @@ jobs:
             --tag ${{ steps.version.outputs.version }} \
             --output CHANGELOG.md
 
-      - name: Generate changelog preview
-        id: changelog_preview
+      - name: Generate release notes preview
+        id: release_notes_preview
         run: |
           {
-            echo 'output<<EOF'
+            echo 'release_notes<<EOF'
             git cliff --config .github/cliff.toml \
               --tag ${{ steps.version.outputs.version }} \
               --unreleased
@@ -80,6 +81,6 @@ jobs:
 
             # Release notes
 
-            ${{ steps.changelog_preview.outputs.output }}
+            ${{ steps.release_notes_preview.outputs.release_notes }}
           labels: release
           token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -0,0 +1,79 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - VERSION
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Build and Publish Release
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out sources
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            make 64tass \
+            python3 python3-pip
+
+      - name: Read the release version
+        id: read_version
+        run: |
+          VERSION="$(cat VERSION | tr -d '\r\n')"
+          if [ -z "$VERSION" ]; then
+            echo "VERSION file is empty."
+            exit 1
+          fi
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Version is $VERSION"
+
+      - name: Build the release
+        run: |
+          make -C source -B release V=1
+
+      - name: Create release archive
+        id: release_archive
+        run: |
+          VERSION="${{ steps.read_version.outputs.version }}"
+          PKG="superbasic-v${VERSION}"
+          mkdir -p dist/"$PKG"
+          cp -a .release/. dist/"$PKG"/
+          cd dist && zip -r "$PKG.zip" "$PKG"
+          echo "archive=dist/$PKG.zip" >> $GITHUB_OUTPUT
+
+      - name: Generate release notes
+        id: release_notes
+        run: |
+          {
+            echo 'release_notes<<EOF'
+            git cliff --config .github/cliff.toml \
+              --tag ${{ steps.read_version.outputs.version }} \
+              --unreleased
+            echo 'EOF'
+          } >> $GITHUB_OUTPUT
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.read_version.outputs.version }}
+          name: v${{ steps.read_version.outputs.version }}
+          target_commitish: ${{ github.sha }}
+          body: ${{ steps.release_notes.outputs.release_notes }}
+          draft: true
+          fail_on_unmatched_files: true
+          files: |
+            ${{ steps.release_archive.outputs.archive }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -1,3 +1,6 @@
 .DS_Store
 __pycache__
 .build
+.release
+dist
+**/generated/timestamp.asm

LICENSE

@@ -1,6 +1,8 @@
 MIT License
 
 Copyright (c) 2022 paulscottrobson
+Copyright (c) 2025-present Aleksey Gurtovoy
+Copyright (c) SuperBASIC contributors (https://github.com/FoenixRetro/f256-superbasic/graphs/contributors)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,38 +1,29 @@
 # F256 SuperBASIC
-Improved BASIC for F256 Junior
-
-### Usage
+Improved BASIC for the F256 computers.
 
+## Usage
 SuperBASIC Reference Manual PDF:
 [reference/source/f256jr_basic_ref.pdf](reference/source/f256jr_basic_ref.pdf)
 
-### Developing
+## Local development
 You need Make, Python and 64tass assembler on your machine.
 
-You will also need a few repos besides SuperBASIC.
-SuperBASIC is fully intended to work with the _latest_ Kernel/DOS.
-
 ### Building
 ```
-git clone git@github.com:FoenixRetro/f256-superbasic.git
-git clone git@github.com:WartyMN/Foenix-F256JR-bootscreens.git
-git clone git@github.com:FoenixRetro/f256-microkernel
-git clone git@github.com:FoenixRetro/FoenixMgr
-cd f256-superbasic/source
+# all the builds are done from the `source` directory
+cd source
 
-# this will build everything against/including latest kernel
-make -B pullkernel updatekernel build release
+# full rebuild, pulls latest kernel and bootscreens
+make -B updatekernel updateassets build
 
-# or just build basic
-make -B basic release
+# standard development build
+make -B build
 
-# build w/ support for Gen 2 features
-make -B basic release HARDWARE_GEN=2
+# development build for F256Jr2/K2 hardware
+make -B build HARDWARE_GEN=2
 ```
 
-This will output a set of binary files in the `release/` folder
-and a file called `release/bulk.csv` that shows where those files
-get flashed in memory.
+The build output is stored in the `.build` directory at the repository root.
 
 ### Testing
 
@@ -47,8 +38,8 @@ you can run the following commands to test your build in MAME F256K:
 
 ```
 cd mame
-cp -f ../f256-superbasic/source/release/sb*.bin roms/f256k/    # copy over SuperBASIC ROMs
-./f256 f256 -window -resolution 1280x960                       # run the emulator
+cp -f ../f256-superbasic/.build/sb*.bin roms/f256k/    # copy over SuperBASIC ROMs
+./f256 f256 -window -resolution 1280x960               # run the emulator
 ```
 
 Note that because MAME embeds CRC checksums for all ROMs, you'll see warnings similar to
@@ -77,7 +68,7 @@ try out your build using the `--flash-bulk` command.
 
 Example on Mac:
 ```
-❯ cd release
+❯ cd .build
 ❯ python3 ~/FoenixMgr/fnxmgr.py --port /dev/cu.usbmodemR23963534611 --flash-bulk bulk.csv
 Attempting to program sector 0x3F with lockout.bin
 Binary file uploaded...
@@ -87,12 +78,18 @@ Attempting to program sector 0x01 with sb01.bin
      ...
 ```
 
+### Releasing a new version
+To ensure quality and reproducibility, official releases are handled through GitHub workflows.
+
+The [release PR preparation](/.github/workflows/prepare-release-pr.yml) workflow monitors pushes to `main` and automatically creates or updates [a release PR](https://github.com/FoenixRetro/f256-superbasic/pulls?q=is%3Apr+is%3Aopen+label%3Arelease) that includes all unreleased changes. This PR includes a log of contributions and is assigned a version based on the major and minor numbers in [`source/Makefile`](/source/Makefile), with the patch number determined by the date of the latest contribution.
+
+Merging the release PR updates the [`VERSION`](/VERSION) and [`CHANGESET.md`](/CHANGESET.md) files, then triggers the [final release](/.github/workflows/release.yml) workflow, which publishes the GitHub release.
 
 ### Additional References
 
 - [F256 Documentation Wiki](https://wiki.f256foenix.com)
 - [More information on flashing SuperBASIC to your machine](https://wiki.f256foenix.com/index.php?title=Kernel_%26_SuperBASIC_Updates)
 - [More information on MAME for F256](https://wiki.f256foenix.com/index.php?title=Emulation#MAME)
 - [F256 MicroKernel](https://github.com/FoenixRetro/f256-microkernel)
-- [F256 Boot Screens](https://github.com/WartyMN/Foenix-F256JR-bootscreens)
+- [F256 Boot Screens](https://github.com/FoenixRetro/f256-bootscreens)
 - [F256 Command Line USB upload tool](https://github.com/pweingar/FoenixMgr)

TODO

@@ -0,0 +1 @@
+1.0.2024-02-11