Release PyGAD 3.8.0

.github/workflows/main.yml

@@ -18,7 +18,11 @@ on:
       - 'examples/**'
       - 'requirements.txt'
       - 'pyproject.toml'
+      - 'setup.py'
+      - 'MANIFEST.in'
       - '.github/workflows/main.yml'
+      - '.github/workflows/release.yml'
+      - 'tools/release.py'
   # Test relevant pull requests, including fork contributions, against master.
   pull_request:
     branches:
@@ -29,9 +33,15 @@ on:
       - 'examples/**'
       - 'requirements.txt'
       - 'pyproject.toml'
+      - 'setup.py'
+      - 'MANIFEST.in'
       - '.github/workflows/main.yml'
+      - '.github/workflows/release.yml'
+      - 'tools/release.py'
   # Allows manual triggering of the workflow from the GitHub Actions tab.
   workflow_dispatch:
+  # Release tags run this same matrix before publishing.
+  workflow_call:
 
 jobs:
   pytest:
@@ -114,8 +124,13 @@ jobs:
       # This includes our new tests for visualization, operators, parallel processing, etc.
       - name: Run Tests
         run: |
+          # Run outside the checkout so imports exercise the installed wheel.
+          cd "$RUNNER_TEMP"
+          python -c "import pygad; print('Testing installed package:', pygad.__file__)"
           if [ "${{ matrix.python-version }}" == "3.14" ] || [ "${{ matrix.python-version }}" == "3.8" ]; then
-            pytest --ignore=tests/test_kerasga.py --ignore=tests/test_torchga.py
+            python -m pytest "$GITHUB_WORKSPACE/tests" \
+              --ignore="$GITHUB_WORKSPACE/tests/test_kerasga.py" \
+              --ignore="$GITHUB_WORKSPACE/tests/test_torchga.py"
           else
-            pytest
+            python -m pytest "$GITHUB_WORKSPACE/tests"
           fi

.github/workflows/release.yml

@@ -2,7 +2,8 @@ name: release
 
 # On a version tag this builds the package once, publishes it to PyPI via
 # trusted publishing (no API token stored in the repo), and attaches the built
-# wheel and sdist to a GitHub Release for the tag. The PyPI project must list
+# wheel and sdist downloaded back from PyPI to a GitHub Release for the tag.
+# Both downloads must match the checked build. The PyPI project must list
 # this repo and workflow as a trusted publisher first.
 
 on:
@@ -11,14 +12,33 @@ on:
     tags:
       - '[0-9]+.[0-9]+.[0-9]+'
 
+permissions:
+  contents: read
+
 jobs:
+  tests:
+    uses: ./.github/workflows/main.yml
+    permissions:
+      contents: read
+
   build:
+    needs: tests
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
+      - name: Verify release tag matches package version
+        run: |
+          python - <<'PY'
+          import os
+          import runpy
+          version = runpy.run_path("pygad/_version.py")["__version__"]
+          tag = os.environ["GITHUB_REF_NAME"]
+          if tag != version:
+              raise SystemExit(f"Release tag {tag} does not match package version {version}")
+          PY
       - name: Build distributions
         run: |
           pip install build . pytest responses 'vilvik>=0.5.3'
@@ -28,10 +48,21 @@ jobs:
         run: |
           pip install twine
           python -m twine check dist/*
+      - name: Check documentation
+        run: |
+          pip install -r docs/requirements.txt
+          python docs/markdown_compatibility.py
+          python -m sphinx -b html -W --keep-going docs/source docs/build/html
+      - name: Prepare documented release notes
+        run: python tools/release.py notes "$GITHUB_REF_NAME" release-notes.md
       - uses: actions/upload-artifact@v4
         with:
           name: dist
           path: dist/
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-notes
+          path: release-notes.md
 
   publish:
     needs: build
@@ -48,22 +79,35 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
 
   github-release:
-    needs: build
+    needs: [build, publish]
     runs-on: ubuntu-latest
     permissions:
       contents: write
     steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
       - uses: actions/download-artifact@v4
         with:
           name: dist
           path: dist/
-      - name: Attach the built files to the GitHub release
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-notes
+      - name: Download and verify the published PyPI distributions
+        run: python tools/release.py fetch-pypi "$GITHUB_REF_NAME" dist published-dist
+      - name: Publish GitHub release with documented notes and PyPI files
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          gh release create "$GITHUB_REF_NAME" dist/* \
-            --repo "$GITHUB_REPOSITORY" \
-            --title "$GITHUB_REF_NAME" \
-            --generate-notes \
-          || gh release upload "$GITHUB_REF_NAME" dist/* \
-            --repo "$GITHUB_REPOSITORY" --clobber
+          if gh release view "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            gh release upload "$GITHUB_REF_NAME" published-dist/* \
+              --repo "$GITHUB_REPOSITORY" --clobber
+            gh release edit "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" \
+              --title "PyGAD $GITHUB_REF_NAME" --notes-file release-notes.md --draft=false --latest
+          else
+            gh release create "$GITHUB_REF_NAME" published-dist/* \
+              --repo "$GITHUB_REPOSITORY" --verify-tag --latest \
+              --title "PyGAD $GITHUB_REF_NAME" --notes-file release-notes.md
+          fi

MANIFEST.in

@@ -0,0 +1,2 @@
+include tools/release.py
+include docs/source/releases.md

README.md

@@ -30,6 +30,8 @@ The library is under active development and more features are added regularly. I
 
 # Installation
 
+The current release is [PyGAD 3.8.0](https://github.com/ahmedfgad/GeneticAlgorithmPython/releases/tag/3.8.0), dated October 9, 2026. Read the [release notes](https://github.com/ahmedfgad/GeneticAlgorithmPython/blob/3.8.0/docs/source/releases.md#pygad-380) for its new features, fixes, and compatibility changes. PyGAD requires Python 3.8 or newer.
+
 To install [PyGAD](https://pypi.org/project/pygad), use pip to download and install the library from [PyPI](https://pypi.org/project/pygad) (Python Package Index). The library is available on PyPI at this page: https://pypi.org/project/pygad.
 
 Install PyGAD with the following command:
@@ -46,6 +48,9 @@ pip install pygad[visualize]
 
 # Training Keras/PyTorch models (pygad.kerasga, pygad.torchga):
 pip install pygad[deep_learning]
+
+# PDF reports need ReportLab and matplotlib:
+pip install pygad[report]
 ```
 
 To get started with PyGAD, read the documentation at [Read the Docs](https://pygad.readthedocs.io).

RELEASING.md

@@ -1,35 +1,58 @@
 # Releasing
 
 Releases are automated. Pushing a version tag builds the package, publishes it to
-PyPI, and attaches the built files to a GitHub Release. Nothing is uploaded by
-hand.
+PyPI, and downloads the published wheel and source distribution for the GitHub
+Release. Downloaded files must match the checked build's SHA-256 hashes.
+The GitHub Release uses the release notes from `docs/source/releases.md`.
 
 ## Steps
 
 1. Bump the version in `pygad/_version.py`. This is the only place the version
    lives.
-2. Update the release notes in the docs if you keep them there.
+2. Update the matching `PyGAD <version>` section in `docs/source/releases.md`.
+   Set `Release Date: Month D, YYYY.` and remove pending-publication text.
 3. Commit and push:
    ```bash
-   git add pygad/_version.py
-   git commit -m "Release 3.6.1"
+   git add pygad/_version.py docs/source/releases.md
+   git commit -m "Prepare PyGAD 3.8.0"
    git push
    ```
-4. Wait for the test workflow (`main.yml`) to pass on that commit.
-5. Tag the release and push the tag:
+   Stage any other intended release changes before committing. Preparation stays
+   on `github-actions` until the maintainer chooses the final release commit;
+   these steps do not require changes to `master`.
+4. Wait for the test workflow (`main.yml`) to pass on that commit. Confirm the
+   release notes describe the intended version and replace its pending release
+   date with the actual publication date. Documentation reads the package version
+   automatically. Build and check the distributions before tagging:
    ```bash
-   git tag 3.6.1
-   git push origin 3.6.1
+   python -m build
+   python -m twine check dist/*
+   ```
+5. Create or update a pull request from `github-actions` to `master`, using the
+   documented release notes as its description. Generate the description with:
+   ```bash
+   python tools/release.py notes 3.8.0 docs/build/release-notes-3.8.0.md
+   ```
+   Wait for its checks and merge it. Tag the merged `master` commit and push the tag:
+   ```bash
+   git switch master
+   git pull --ff-only origin master
+   git tag 3.8.0
+   git push origin 3.8.0
    ```
 
-The `release` workflow does the rest: it builds the wheel and sdist, publishes
-them to PyPI, and creates a GitHub Release with both files attached. Follow it
-with `gh run watch` or the Actions tab.
+The `release` workflow first runs the full Python 3.8 through 3.14 test matrix,
+then builds the wheel and sdist, checks documentation and release notes, and
+publishes the packages to PyPI. It downloads both published files, verifies
+their SHA-256 hashes against the build, and creates a GitHub Release with those
+files and the documented notes. Documentation links in the PR and release notes
+point to the tagged source. Follow the workflow with `gh run watch` or the Actions tab.
+Verify the PyPI version and GitHub assets after it succeeds.
 
 ## Rules
 
 - The tag must match `pygad/_version.py` and is the bare version number with no
-  `v` prefix, for example `3.6.1`. The tag is what triggers the release.
+  `v` prefix, for example `3.8.0`. The tag is what triggers the release.
 - Every release needs a new version number. PyPI does not allow re-uploading or
   overwriting a version that already exists.
 - Do not run `twine upload` or upload files to the GitHub Release by hand. The

docs/MARKDOWN.md

@@ -0,0 +1,41 @@
+# Writing Documentation in Markdown
+
+Documentation pages should be readable on GitHub and in Markdown previews as well as on Read the Docs. Use ordinary Markdown for headings, links, images, lists, tables, and code blocks.
+
+For links within the documentation, use a relative `.md` path and the GitHub-style heading anchor:
+
+```markdown
+[Plot Lifecycle](visualize.md#plot_lifecycle)
+```
+
+MyST resolves these links to the appropriate pages and section IDs during a Sphinx build. Existing published anchors remain available. Builds report missing pages and heading anchors.
+
+Use HTML `<details>` and `<summary>` for collapsible descriptions. Leave blank lines around their Markdown content. Use `<code>` for code in a summary because Markdown formatting is not processed inside the summary itself:
+
+```markdown
+<details>
+<summary><code>gene_type=float</code>: Data type of the genes.</summary>
+
+The type used to store each gene value.
+
+</details>
+```
+
+The `markdown_compatibility.py` extension converts these blocks into the existing Sphinx Design dropdowns for HTML and other documentation formats.
+
+Keep Sphinx-only metadata, such as explicit labels and toctrees, inside `<!-- sphinx ... -->` comments. The extension restores this metadata during a build; Markdown previews hide it. A toctree should have visible Markdown navigation beside it, either a list on the home page or a navigation group:
+
+```markdown
+<!-- navigation-grid: 1 2 2 3 -->
+
+- [Controlling Gene Values](gene_values.md) — Set ranges, types, constraints, and duplicate prevention.
+- [Controlling Generations](generations.md) — Configure stopping, elitism, and continuation.
+
+<!-- /navigation-grid -->
+```
+
+The build presents these lists as the existing navigation cards. Their titles, destinations, and descriptions are written only once.
+
+For diagrams with a preferred display width, put a normal PNG image and its caption between `documentation-figure` comments, following the existing pages. The image works directly in Markdown; the build restores the centered figure, caption, and width and selects the appropriate image format. Embedded videos stay in Sphinx comments with a visible YouTube link beside them.
+
+Python example sections are generated from the catalog and shared templates. See [Connecting Python Examples to the Documentation](PYTHON_EXAMPLES.md) for the editing and checking commands. Regeneration needs only Python; it does not require Sphinx or execute the examples.

docs/PYTHON_EXAMPLES.md

@@ -0,0 +1,45 @@
+# Connecting Python Examples to the Documentation
+
+`python_examples.json` is the shared catalog for the Examples index and the Python example cards in the guides. Keep the descriptions and requirements here rather than copying them into each guide. Paths are relative to the repository's `examples/` directory.
+
+For the general documentation conventions, see [Writing Documentation in Markdown](MARKDOWN.md).
+
+To show one or more examples beside a relevant explanation, use this template in a documentation page:
+
+```markdown
+<!-- python-examples
+example_initial_population.py
+example_gene_type_conversion.py
+-->
+
+<!-- /python-examples -->
+```
+
+After changing the catalog or adding a section, update the checked-in Markdown from the repository root:
+
+```console
+python docs/markdown_compatibility.py --update-examples
+```
+
+The generated section contains ordinary Markdown links, descriptions, and expandable run instructions. It is readable on GitHub and in Markdown previews before any build. Do not edit the generated text directly; edit the catalog or shared templates, then regenerate it. To check that the generated sections are current, run `python docs/markdown_compatibility.py`.
+
+For larger groups, the section uses a compact table with expandable run instructions. The Examples index uses `python-examples-index` comments to list every entry by topic, with links back to its guide. Sphinx presents these sections using the existing example cards, tables, dropdowns, and downloads.
+
+Each catalog entry has these fields:
+
+- `path`: Existing Python script or notebook under `examples/`.
+- `title`: Short descriptive name for the example.
+- `description`: What readers will learn from the script.
+- `category`: Topic heading in the Examples index. Categories follow their first appearance in the catalog.
+- `guide`: Existing Markdown guide, relative to `docs/source/`.
+- `requirements`: Libraries or optional extras needed in addition to a matching version of PyGAD.
+- `run`: Command to run from the repository root, or an empty string for a notebook.
+- `run_note` (optional): Working-directory instructions when the root cannot be used directly.
+- `data` (optional): Dataset filenames, expected layout, and any setup limitations.
+- `download` (optional, default `true`): Set to `false` when downloading a script alone would omit required data or companion files. Readers receive a folder link instead.
+
+The shared templates are in `python_example_templates/`. The `*-source.md.template` files use standard Markdown and generate the checked-in sections. The `.md.jinja` files use Sphinx Design cards and dropdowns and Sphinx's native download links. Both presentations use the same catalog. The `markdown_compatibility.py` extension checks the source sections and passes them to `python_examples.py` for the built presentation; neither executes example scripts.
+
+The documentation build checks that every Python script appears in the catalog, all catalog paths stay inside `examples/`, and the linked guides exist. Missing entries, unknown paths, incomplete section comments, and stale generated Markdown fail the build so examples are not silently left out. Sphinx copies downloadable scripts from the repository into the built documentation; no second script copy needs to be maintained.
+
+GitHub links use the commit checked out for the documentation build. Without Git, the configured Read the Docs identifier is used, falling back to `master`. This keeps source links aligned with versioned documentation.