soargroup/release-support

release-support's Issues

test spaces in paths

We don't have any CI for the executables released here, but when we do, we should try running all of the included scripts in a path with spaces, just to make sure we've used quotes everywhere we need to.

Update manual for chunking changes from Mazin's Dissertation

Notes from Mazin:

• The chapter in the manual on procedural learning is out of date.
  • Remove old terminology (DPKL, EBC, operationality) and update with current stuff from thesis
  • If the explainer were removed, the parts about it would also need to be removed.
• Add something about what is included in stats (for e.g. duplicates don’t increment anything). Why some numbers can be larger than totals.
• Add something to gds and chunking chapters that GDS does not monitor negative conditions

installable packages

It would be nice to be able to install Soar automatically via a package manager:

• Mac: Homebrew
• Windows: NuGet
• Linux: RPM, DEB

Alternatively, perhaps pip.

re-structure release

There's some feedback that the release structure is not ideal, and it seems to be put together under outdated assumptions of size limitations. Ideally there should only be a single multiplatform release zip (so the tutorial should always be included), and the manual should be included as well. Further details need to be hashed out. @marinier

Add set math RHS functions to manual

These were added in 9.6.1 for JSoar compatibility, and we didn't have the time to introduce new manual sections for them.

ensure __MACOSX files aren't in distribution

When opening the distribution on Windows, I noticed hidden Mac OSX files. Update the python script that zips everything together to ensure we are not including such hidden backup files.

Migrate SML quickstart into Soar distribution documentation

The SML quickstart guide is only available on the website, and today the website is out. Move the SML guide into a new docs/ folder in markdown format, then generate a PDF and include it in the next distribution. This will be a good start to #9, as well (in terms of it being markdown and also gathering docs in one place).

migrate batch files to powershell

PowerShell has a linter plugin for VSCode, and is considered all around quite nice. There isn't really any linter for batch files, unfortunately. It appears that Windows 7 and newer comes with PowerShell by default, and XP service pack 3 included it, as well. Not sure about Vista.

Tutorial PDFs not rendered fully correctly

In the tutorial download, part 2 has some rendering issues. E.g., in section 7.3 (page 87) the red box callouts pointing to the rule are all blank. Looking at the original word docs it looks fine.

I haven't looked at the other parts of the tutorial to see how widespread this is.

Fully automate release

Current release process:

• Clone all of SoarGroup's repos into a directory
• generate the manual via the makefile under ManualSource, or grab the built one from CI. It should be placed in the pdf directory.
• Download the Windows, Mac (x86-64) and Linux builds of Soar from the desired GH action workflow result
• Build the mac_ARM64 version locally (hope you have an M1 or M2 computer :) GH doesn't offer CI for it yet)
• Gather the following jar's under SoarShuffler/jars:
  • Eaters_TankSoar.jar
  • VisualSoar.jar
  • commons-logging-1.1.1.jar
  • log4j-1.2.15.jar
  • stopwatch-0.4-with-deps.jar

VisualSoar and Eaters_TankSoar must be built from their repositories (although I had to fix VisualSoar, see SoarGroup/VisualSoar#1), and the others are in the lib/ directory in the VisualSoar repository. Note that the log4j one is not affected by the famous security bug.

• Set your environment variables for SoarShuffler. Here's my .env for an example:

export SOAR_RELEASE_VERSION=9.6.1
export SOAR_SHUFFLER_OUTPUT_DIR=./SoarRelease
export SOAR_WIN_X86_64_COMPILED_DIR=~/Downloads/Soar_windows-x86-64_out
export SOAR_LINUX_X86_64_COMPILED_DIR=~/Downloads/Soar_linux-x86-64_out
export SOAR_MAC_X86_64_COMPILED_DIR=~/Downloads/Soar_mac-x86-64_out
export SOAR_MAC_ARM64_COMPILED_DIR=~/dev/workspaces/c_workspace/Soar/out
export SOAR_GROUP_REPOS_HOME=~/dev/workspaces/c_workspace/

• Run SoarShuffle:

  cd SoarShuffle
  python3 soar_shuffler.py Soar_Projects_Filelist.txt

You'll get the release directories wherever you specified in the SOAR_SHUFFLER_OUTPUT_DIR env var.

Mac install should check for Rosetta mode

Use sysctl -n sysctl.proc_translated, which returns 1 when running under Rosetta and 0 otherwise. If running under Rosetta, we should install the x86-64 binaries, not the ARM64 ones.

if [ $(sysctl -n sysctl.proc_translated) ]
then
    echo "Rosetta"
else
    echo "Not Rosetta"
fi

convert current PDF content to HTML and host online

Would be really nice for discoverability, and I think also usability, to have all of the tutorials as well as the manual in HTML form hosted next to the API documentation and everything else we have for Soar.