Merge pull request #2279 from AllenInstitute/bugfix/2279-better-manua…

…l-installation-instructions

Enhance manual installation instructions

.github/workflows/build-pr.yml

@@ -83,7 +83,7 @@ jobs:
           fetch-depth: 0 # load all commits
       - name: Initial repo config
         run: tools/initial-repo-config.sh
-      - name: Create installer
+      - name: Create release package and installer
         run: tools/create-installer.sh ${{ fromJSON('["", "dev"]')[ matrix.kind == 'dev' ] }}
       - name: Sign installer
         run: tools/sign-installer.sh -p '${{ secrets.GHA_MIES_CERTIFICATE_PIN }}'
@@ -93,6 +93,7 @@ jobs:
         with:
           name: BuildInstaller-${{ matrix.kind }}-assets
           path: |
+            *.zip
             tools/installer/MIES-*.exe
           if-no-files-found: error
 

Packages/doc/developers.rst

@@ -1,15 +1,19 @@
 Developer
 =========
 
+.. _getting MIES:
+
 Getting MIES
 ------------
 
-Latest development version from main branch
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Cloning the MIES repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 -  ``git clone --recurse-submodules https://github.com/AllenInstitute/MIES``
--  ``./tools/initial-repo-config.sh`` (Requires a Git Bash shell, named
-   Git terminal in SourceTree)
+-  ``./tools/initial-repo-config.sh`` (Requires a Git Bash/Terminal)
+
+If you only want to **use** MIES and not **develop** it, you can also get the source
+code via the `release package <https://github.com/AllenInstitute/MIES/releases>`__ as zip file.
 
 Building the documentation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -77,12 +81,35 @@ Cutting a new release
 -  Create a new release on github and check that the Github Actions job
    correctly uploads the artifacts
 
+Creating a release package manually
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  Open a git bash terminal by choosing Actions->"Open in terminal" in
+   SourceTree
+-  Checkout the release branch ``git checkout release/$myVersion``
+-  If none exists create one with ``git checkout -b release/$myVersion``
+-  Change to the ``tools`` directory in the worktree root folder
+-  Execute ``./create-release.sh``
+-  The release package including the version information is then
+   available as zip file
+
 Continuous integration server
 -----------------------------
 
 Our `CI server <https://github.com/AllenInstitute/MIES/actions>`__, called
 Github Actions, provides the following services for MIES:
 
+Automatic release package building
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  If a commit is added to the ``main`` or any ``release/*`` branch a CI
+   pipeline is started
+-  In this pipeline are some basic tests executed and a new installer is build.
+   The installer is uploaded to the corresponging release (``latest`` for
+   ``main``).
+-  If the commit is added to the ``main`` branch the CI will also create a new
+   version of the documentation and deploy it to Github Pages.
+
 Compilation testing
 ~~~~~~~~~~~~~~~~~~~
 

Packages/doc/installation.rst

@@ -151,9 +151,9 @@ install via the Installer package.
 Windows (with hardware support)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Install the `Visual C++ Redistributable package` <https://github.com/AllenInstitute/MIES/blob/main/tools/installer/vc_redist.x64.exe>`__.
-
+-  Install the `Visual C++ Redistributable package <https://github.com/AllenInstitute/MIES/blob/main/tools/installer/vc_redist.x64.exe>`__
 -  Quit Igor Pro
+-  Get the MIES source code, see :ref:`getting MIES`
 -  Create the following shortcuts in ``C:\Users\$username\Documents\WaveMetrics\Igor Pro 9 User Files``
 
    -  In ``User Procedures`` a shortcut pointing to
@@ -175,9 +175,9 @@ Windows (without hardware)
 In case you don't have the hardware connected/available which some XOPs
 require, you can also install MIES without any hardware related XOPs present.
 
-Install the `Visual C++ Redistributable package` <https://github.com/AllenInstitute/MIES/blob/main/tools/installer/vc_redist.x64.exe>`__.
-
+-  Install the `Visual C++ Redistributable package <https://github.com/AllenInstitute/MIES/blob/main/tools/installer/vc_redist.x64.exe>`__
 -  Quit Igor Pro
+-  Get the MIES source code, see :ref:`getting MIES`
 -  Create the following shortcuts in
    ``C:\Users\$username\Documents\WaveMetrics\Igor Pro 9 User Files``
 
@@ -206,9 +206,7 @@ MacOSX (without hardware)
 Analysis support only. Data acquisition and NWBv2 export are not supported on MacOSx.
 
 -  Quit Igor Pro
--  Get the MIES source code, see
-   `here <https://alleninstitute.github.io/MIES/developers.html#latest-development-version-from-main-branch>`__
-   for instructions.
+-  Get the MIES source code, see :ref:`getting MIES`
 -  Create the following symlinks in
    ``/Users/$username/Documents/WaveMetrics/Igor Pro 9 User Files``
 
@@ -226,3 +224,17 @@ Analysis support only. Data acquisition and NWBv2 export are not supported on Ma
    -  In ``Igor Help Files`` a shortcut pointing to HelpFiles-IP9
 
 -  Start Igor Pro
+
+JSON Configuration folders
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MIES supports JSON files for loading and storing panel configurations. Although it is
+possible to load files from arbitrary paths manually, one can also put the
+files into one of the following folders
+
+-  ``Packages/Settings`` in the installation location
+
+-  ``C:/ProgramData/AllenInstitute/MIES/Settings``
+
+to execute all of them via :menuselection:`MIES Panels --> Automation --> Load standard configuration`
+or by pressing :kbd:`CONTROL-1`.

tools/upload-github-release-asset-helper.sh

@@ -136,7 +136,7 @@ release_description=$(cat <<EOF
   "tag_name": ${tag_name},
   "target_commitish": ${target_commitish},
   "name": ${name},
-  "body": "Last updated: $(date +"%F %T%z")\n\nThe installer package should work for all users.\n\nSee [here](https://alleninstitute.github.io/MIES/releasenotes.html) for the changelog and [here](https://alleninstitute.github.io/MIES/index.html) for the documentation.",
+  "body": "Last updated: $(date +"%F %T%z")\n\nThe installer package should work for all users. Only windows users wishing to manually install the package need the zip file.\n\nSee [here](https://alleninstitute.github.io/MIES/releasenotes.html) for the changelog and [here](https://alleninstitute.github.io/MIES/index.html) for the documentation.",
   "draft":${draft},
   "prerelease": ${prerelease}
 }

tools/upload-github-release-asset.sh

@@ -4,7 +4,7 @@
 #
 # Expectations:
 # - Github OAuth token is provided as the first argument. (automatically set when running on CI)
-# - The installer package is in the working tree root
+# - The release and installer packages are in the working tree root
 # - Either the main or a release branch are checked out
 
 set -e
@@ -40,9 +40,14 @@ fi
 
 cd $top_level
 
+zipfile=$(ls Release_*.zip)
 installerfile=$(find -name "MIES-Release*.exe")
 
-if [ ! -f $installerfile ]
+if [ ! -f $zipfile ]
+then
+  echo "File $zipfile does not exist"
+  exit 1
+elif [ ! -f $installerfile ]
 then
   echo "File $installerfile does not exist"
   exit 1
@@ -73,4 +78,4 @@ esac
 
 echo "Upload release for tag: $tag"
 
-./tools/upload-github-release-asset-helper.sh github_api_token=$github_token owner=AllenInstitute repo=MIES tag=$tag filename=$installerfile
+./tools/upload-github-release-asset-helper.sh github_api_token=$github_token owner=AllenInstitute repo=MIES tag=$tag filename=$zipfile filename=$installerfile