From caa6ab284a824d72bcdd26fe5581d50384daa0f8 Mon Sep 17 00:00:00 2001
From: Phil Burk <philburk@mobileer.com>
Date: Sun, 6 Oct 2024 13:57:36 -0700
Subject: [PATCH] Update build.md

Describe use of ~/Music folder
Add amiga folder.
Add test steps to make sure the release can be run.
---
 docs/build.md | 47 +++++++++++++++++++++++++++++++++++------------
 1 file changed, 35 insertions(+), 12 deletions(-)

diff --git a/docs/build.md b/docs/build.md
index 99e83a5..4705c47 100644
--- a/docs/build.md
+++ b/docs/build.md
@@ -21,11 +21,11 @@ New C/C++ files should only be added using the ProJucer.
 
 ### Checking out the code
 
-    cd ~
-    mkdir Work  # if needed
-    cd Work
-    mkdir hmsl
-    cd hmsl
+HMSL runs in a Sandbox that only allows it to access files in the ~/Music folder.
+
+    cd ~/Music
+    mkdir hmsl_repo  # if needed
+    cd hmsl_repo
     git clone https://github.com/philburk/hmsl.git HMSL
     cd HMSL/pforth
     git submodule init
@@ -52,7 +52,8 @@ Unless you need to add a JUCE file, or update the JUCE version, you can probably
 * Run the application. It will open a terminal window.
 * Enter:   include fth/make_hmsl.fth
 * It will compile HMSL and save a new pforth.dic.
-* Close the terminal window by entering:  BYE
+* Enter:  BYE
+* Close the terminal window.
 * The next time you run the application, it will initialize HMSL.
 
 ### Packaging a Release for Mac OS
@@ -60,12 +61,34 @@ Unless you need to add a JUCE file, or update the JUCE version, you can probably
 2. Update the version number in native/juce/Source/Main.cpp
 3. Update master repository.
 4. Build the app as described above.
-5. Open the folder ~/Work/hmsl/HMSL_Release/HMSL/hmsl.
-6. Replace the JuceHMSL.app file in that folder with "~/Work/hmsl/HMSL/native/juce/Builds/MacOSX/build/Debug/JuceHMSL.app".
-7. Replace the pforth.dic file with "~/Work/hmsl/HMSL/hmsl/pforth.dic".
-8. Replace the "pieces" folder with "~/Work/hmsl/HMSL/hmsl/pieces".
-8. Replace the "tools" folder with "~/Work/hmsl/HMSL/hmsl/tools".
+5. Open the folder ~/Work/hmslWork/HMSL_Release/HMSL/hmsl.
+6. Replace the JuceHMSL.app file in that folder with "~/Music/hmsl_repo/HMSL/native/juce/Builds/MacOSX/build/Debug/JuceHMSL.app".
+7. Replace the pforth.dic file with "~/Music/hmsl_repo/HMSL/hmsl/pforth.dic".
+8. Replace the "pieces" folder with "~/Music/hmsl_repo/HMSL/hmsl/pieces".
+8. Replace the "tools" folder with "~/Music/hmsl_repo/HMSL/hmsl/tools".
+8. Replace the "amiga" folder with "~/Music/hmsl_repo/HMSL/hmsl/amiga".
 9. Make a zip file from HMSL_Release/HMSL.
 10. Rename it "HMSL_{version}.zip" using underscores, eg. "HMSL_0_5_5.zip"
-11. Under Releases, create a new release and drag the new ZIP file to attach it.
+
+### Test the Release
+1. Drag the ZIP file to a folder on Google Drive.
+1. Download the ZIP file to ~/Downloads.
+1. Uncompress the ZIP file and drag the resulting "HMSL" folder into ~/Music.
+1. Hold down the Ctrl key and right click on the JuceHMSL.app icon.
+2. Click the Open button. (If you are an expert in Apple certificates, please open an Issue and offer to help me fix this.)
+1. HMSL should ask you to initialize by entering: y
+2. Wait 5 seconds for HMSL to initialize.
+1. Enter: SHEP
+1. You should hear some notes and see the Shape Editor appear.
+3. Close the Shape Editor window.
+4. Enter:  include hap:swirl.fth
+5. Enter:  swirl
+6. Hear some odd bells and an "Uhh" sound.
+7. Clock the "Forward" button. The shape should start rotating in a {time,pitch} space.
+8. Close the SWIRL window.
+
+
+## Make a Release on GitHub
+1. Look at the PRs and Commits since the last Release and prepare Release Notes.
+1. Under Releases, create a new release and drag the new ZIP file to attach it.