Improve building and releasing documentation and process

* Updates release documentation in developer docs
* Creates a new `GAMBIT_VERSION` file as the single place where version number needs to be updated.
* Organises build support files in a single directory with OS-specific subdirectories.

Closes #560

Author: edwardchalstrey1

.github/workflows/tools.yml

@@ -91,7 +91,7 @@ jobs:
         run: |
           mkdir installer
           cp gambit* installer
-          "${WIX}bin/candle" gambit.wxs
+          "${WIX}bin/candle" build_support/msw/gambit.wxs
           "${WIX}bin/light" -ext WixUIExtension gambit.wixobj
       - uses: actions/upload-artifact@v5
         with:

Makefile.am

@@ -23,11 +23,9 @@
 ACLOCAL_AMFLAGS = -I m4
 
 EXTRA_DIST = \
-	gambit.spec \
-	gambit.desktop \
-    gambit.wxs \
-	contrib/mac/Info.plist \
-	contrib/mac/gambit.icns \
+    build_support/msw/gambit.wxs.in \
+	build_support/osx/Info.plist.in \
+	build_support/osx/gambit.icns \
 	src/labenski/README.txt \
 	src/labenski/art/grab.xpm \
 	src/labenski/art/hand.xpm \
@@ -374,9 +372,12 @@ if WITH_GUI
 bin_PROGRAMS += gambit
 endif
 
-EXTRA_PROGRAMS = gambit-enumpoly gambit
+# Read version from GAMBIT_VERSION file for use in compilation
+GAMBIT_VERSION = $(shell cat $(top_srcdir)/build_support/GAMBIT_VERSION)
+
+# Define VERSION for all C++ compilations and set include paths
+AM_CPPFLAGS = -I$(top_srcdir)/src -DVERSION=\"$(GAMBIT_VERSION)\"
 
-AM_CPPFLAGS = -I$(top_srcdir)/src -I$(top_srcdir)/src/labenski/include ${WX_CXXFLAGS}
 AM_CXXFLAGS = ${LLVM_CXXFLAGS}
 
 ## Command-line tools
@@ -604,6 +605,9 @@ gambit_SOURCES = \
 	src/gui/valnumber.cc \
 	src/gui/valnumber.h
 
+# Add wxWidgets compilation flags for the GUI program
+gambit_CXXFLAGS = $(AM_CXXFLAGS) $(WX_CXXFLAGS)
+gambit_CPPFLAGS = $(AM_CPPFLAGS) $(WX_CXXFLAGS) -I$(top_srcdir)/src/labenski/include
 
 if IS_WIN32
 gambit_LDADD = $(RC_OBJECT_PATH) $(WX_LIBS_STATIC) -ldeflate -lzstd -llerc -lWebP
@@ -619,8 +623,8 @@ osx-bundle:
 	-mkdir Gambit.app/Contents
 	-mkdir Gambit.app/Contents/MacOS
 	-mkdir Gambit.app/Contents/Resources
-	cp ${top_srcdir}/contrib/mac/Info.plist Gambit.app/Contents
-	cp ${top_srcdir}/contrib/mac/gambit.icns Gambit.app/Contents/Resources/gambit.icns
+	cp build_support/osx/Info.plist Gambit.app/Contents
+	cp ${top_srcdir}/build_support/osx/gambit.icns Gambit.app/Contents/Resources/gambit.icns
 	echo -n 'APPL????' > Gambit.app/Contents/PkgInfo
 	cp gambit Gambit.app/Contents/MacOS/gambit
 	cp ${bin_PROGRAMS} Gambit.app/Contents/MacOS
@@ -635,11 +639,11 @@ osx-dmg:  osx-bundle
 msw-msi:
 	-mkdir installer
 	cp gambit* installer
-	candle gambit.wxs
+	candle build_support/msw/gambit.wxs
 	light -ext WixUIExtension gambit.wixobj
 
 clang-tidy:
-	clang-tidy ${top_srcdir}/src/core/*.cc -- --std=c++17 -I ${top_srcdir}/src -DVERSION=""
-	clang-tidy ${top_srcdir}/src/games/*.cc ${top_srcdir}/src/games/*/*.cc -- --std=c++17 -I ${top_srcdir}/src -DVERSION=""
-	clang-tidy ${top_srcdir}/src/solvers/*/*.cc -- --std=c++17 -I ${top_srcdir}/src -DVERSION=""
-	clang-tidy ${top_srcdir}/src/tools/*/*.cc -- --std=c++17 -I ${top_srcdir}/src -DVERSION=""
+	clang-tidy ${top_srcdir}/src/core/*.cc -- --std=c++17 -I ${top_srcdir}/src -DVERSION=\"$(GAMBIT_VERSION)\"
+	clang-tidy ${top_srcdir}/src/games/*.cc ${top_srcdir}/src/games/*/*.cc -- --std=c++17 -I ${top_srcdir}/src -DVERSION=\"$(GAMBIT_VERSION)\"
+	clang-tidy ${top_srcdir}/src/solvers/*/*.cc -- --std=c++17 -I ${top_srcdir}/src -DVERSION=\"$(GAMBIT_VERSION)\"
+	clang-tidy ${top_srcdir}/src/tools/*/*.cc -- --std=c++17 -I ${top_srcdir}/src -DVERSION=\"$(GAMBIT_VERSION)\"

build_support/GAMBIT_VERSION

@@ -0,0 +1 @@
+16.4.0

gambit.wxs build_support/msw/gambit.wxs.ingambit.wxs renamed to build_support/msw/gambit.wxs.in

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
-    <Product Id="8EE11AE3-2B91-4870-895B-44C46D648BD6" Name="Gambit 16" Language="1033" Version="16.4.0" Manufacturer="The Gambit Project" UpgradeCode="135FFB28-DA7C-427C-A3DA-783B805BCC22">
+    <Product Id="8EE11AE3-2B91-4870-895B-44C46D648BD6" Name="Gambit 16" Language="1033" Version="@GAMBIT_VERSION@" Manufacturer="The Gambit Project" UpgradeCode="135FFB28-DA7C-427C-A3DA-783B805BCC22">
         <Package Description="Gambit" Comments="Software Tools for Game Theory" InstallerVersion="200" Compressed="yes" />
         <Media Id="1" Cabinet="gambit.cab" EmbedCab="yes" />
 

contrib/mac/Info.plist build_support/osx/Info.plist.incontrib/mac/Info.plist renamed to build_support/osx/Info.plist.in

@@ -19,13 +19,13 @@
 	<key>CFBundleSignature</key>
 	<string>????</string>
 	<key>CFBundleVersion</key>
-	<string>16.4.0</string>
+	<string>@GAMBIT_VERSION@</string>
 	<key>CFBundleShortVersionString</key>
-	<string>16.4.0</string>
+	<string>@GAMBIT_VERSION@</string>
 	<key>CFBundleGetInfoString</key>
-	<string>Gambit version 16.4.0, (c) 1994-2025 The Gambit Project</string>
+	<string>Gambit version @GAMBIT_VERSION@, (c) 1994-2025 The Gambit Project</string>
 	<key>CFBundleLongVersionString</key>
-	<string>16.4.0, (c) 1994-2025 The Gambit Project</string>
+	<string>@GAMBIT_VERSION@, (c) 1994-2025 The Gambit Project</string>
 	<key>NSHumanReadableCopyright</key>
 	<string>Copyright 1994-2025 The Gambit Project</string>
 	<key>LSRequiresCarbon</key>

contrib/mac/gambit.icns build_support/osx/gambit.icnscontrib/mac/gambit.icns renamed to build_support/osx/gambit.icns

@@ -20,7 +20,7 @@ dnl along with this program; if not, write to the Free Software
 dnl Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 dnl
 
-AC_INIT([gambit],[16.4.0])
+AC_INIT([gambit],[m4_esyscmd_s([cat build_support/GAMBIT_VERSION])])
 AC_CONFIG_SRCDIR([src/gambit.h])
 AM_INIT_AUTOMAKE([subdir-objects foreign])
 dnl AC_CONFIG_MACRO_DIR([m4])
@@ -145,5 +145,8 @@ AC_SUBST(WX_CXXFLAGS)
 REZFLAGS=`echo $CXXFLAGS $WX_CXXFLAGS | sed 's/-mthreads//g' | sed 's/-g//g' | sed 's/-O. / /g' | sed 's/-I/--include-dir /g'`
 AC_SUBST(REZFLAGS)
 
-AC_CONFIG_FILES([Makefile])
+GAMBIT_VERSION=`cat build_support/GAMBIT_VERSION`
+AC_SUBST(GAMBIT_VERSION)
+
+AC_CONFIG_FILES([Makefile build_support/osx/Info.plist build_support/msw/gambit.wxs])
 AC_OUTPUT

configure.ac

@@ -1,3 +1,5 @@
+import pathlib
+
 #
 # Gambit documentation build configuration file, created by
 # sphinx-quickstart on Sun Mar 21 14:35:06 2010.
@@ -53,10 +55,17 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-# The short X.Y version.
-version = "16.4"
-# The full version, including alpha/beta/rc tags.
-release = "16.4.0"
+
+_version_file = pathlib.Path(__file__).parent.parent / "build_support/GAMBIT_VERSION"
+if _version_file.exists():
+    _full_version = _version_file.read_text().strip()
+    # The short X.Y version.
+    version = ".".join(_full_version.split(".")[:2])
+    # The full version, including alpha/beta/rc tags.
+    release = _full_version
+else:
+    # Throw error if GAMBIT_VERSION file not found
+    raise FileNotFoundError("GAMBIT_VERSION file not found")
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/conf.py

@@ -160,3 +160,60 @@ To add a contributor, comment on a GitHub Issue or Pull Request, asking @all-con
  @all-contributors please add @<username> for <contributions>
 
 Refer to the `emoji key <https://allcontributors.org/docs/en/emoji-key>`__ for a list of contribution types.
+
+Releases & maintenance branches
+-------------------------------
+
+Releases of Gambit are made by core developers.
+Details of previous releases can be found in the `GitHub releases page <https://github.com/gambitproject/gambit/releases>`__.
+
+Branches labeled ``maintX`` and ``maintX_Y``, where ``X`` is the major version number and ``Y`` is the minor version number, are associated with releases and point to the latest commit on a stable version.
+Navigate to the Gambit repository on GitHub and select the `branches` tab to see the list of active maintenance branches.
+Be sure to delete any maintenance branches that are no longer being maintained.
+
+.. _making-a-new-release:
+
+Making a new release
+^^^^^^^^^^^^^^^^^^^^
+
+When making a new release of Gambit, follow these steps:
+
+1. Create a new branch from the latest commit on the ``master`` branch named ``maintX_Y``, where ``X`` is the major version number and ``Y`` is the minor version number of the new release.
+
+2. Update the version number in the ``build_support/GAMBIT_VERSION`` file to ``X.Y.Z``.
+
+   All other files will automatically use the updated version number:
+
+   - `pyproject.toml` reads from GAMBIT_VERSION file at build time
+   - `configure.ac` reads from GAMBIT_VERSION file and substitutes into `build_support/osx/Info.plist` and `build_support/msw/gambit.wxs`
+   - `src/pygambit/__init__.py` reads from installed package metadata or GAMBIT_VERSION file
+   - `doc/conf.py` reads from GAMBIT_VERSION file at documentation build time
+   - Documentation pages reference the `|release|` substitution variable to automatically reflect the updated version number.
+
+3. Update the `ChangeLog` file with a summary of changes
+
+4. Once there are no further commits to be made for the release, create a tag for the release from the latest commit on the maintenance branch. ::
+
+    git tag -a vX.Y.Z -m "Gambit version X.Y.Z"
+
+5. Push the maintenance branch and tags to the GitHub repository. ::
+
+    git push origin maintX_Y
+    git push origin --tags
+
+6. Create a new release on the `GitHub releases page <https://github.com/gambitproject/gambit/releases>`__, using the tag created in step 4.
+   Include a summary of changes from the `ChangeLog` file in the release notes.
+
+7. Currently there is no automated process for pushing the new release to PyPI. This must be done manually.
+
+.. TODO: update this process to be automated via GitHub Actions: Issue #557
+
+Patching maintained versions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you have bug fixes that should be applied across maintained versions:
+
+1. Make a branch from the oldest maintenance branch to which the change applies
+2. Apply the change and make a pull request to that maintenance branch
+3. After the pull request is merged, open new pull requests to each subsequent maintenance branch and finally to the master branch, merging each in turn
+4. Create new releases from each maintenance branch as needed, following the steps in :ref:`making-a-new-release`.

doc/developer.contributing.rst

@@ -36,11 +36,11 @@ outputting the strategic form of the game in one of these formats:
    Suppresses printing of the banner at program launch.
 
 
-Example invocation for HTML output::
+Example invocation for HTML output
 
    $ gambit-convert -O html 2x2.nfg
    Convert games among various file formats
-   Gambit version 16.4.0, Copyright (C) 1994-2025, The Gambit Project
+   Gambit version |release|, Copyright (C) 1994-2025, The Gambit Project
    This is free software, distributed under the GNU GPL
 
    <center><h1>Two person 2 x 2 game with unique mixed equilibrium</h1></center>
@@ -51,11 +51,11 @@ Example invocation for HTML output::
    align=center>1,0</td></tr></table>
 
 
-Example invocation for LaTeX output::
+Example invocation for LaTeX output
 
    $ gambit-convert -O sgame 2x2.nfg
    Convert games among various file formats
-   Gambit version 16.4.0, Copyright (C) 1994-2025, The Gambit Project
+   Gambit version |release|, Copyright (C) 1994-2025, The Gambit Project
    This is free software, distributed under the GNU GPL
 
    \begin{game}{2}{2}[Player 1][Player 2]