Merge pull request #96 from easyscience/develop

Release: merge develop into master

Author: AndrewSazonov

.github/workflows/build-docs.yml

@@ -1,13 +1,32 @@
+# This workflow builds and deploys documentation for the project.
+#
+# Steps overview:
+#  Job 1: build-docs
+#   - Builds documentation (including running Jupyter notebooks to generate output cells).
+#   - Uploads the built site as a Pages artifact.
+#  Job 2: deploy-dev
+#   - Deploys the built site to GitHub Pages for development (pushes to develop/master).
+#  Job 3: deploy-prod
+#   - Deploys the built site to gh_pages branch for production (release tags starting with v*).
+#   - This triggers deployment to a custom domain via webhook.
+#
+# The action summary page will contain links to the built artifact for downloading
+# and inspecting, as well as links to both the development and production versions of
+# the deployed documentation site.
+
 name: Build and deploy docs
 
 on:
+  # Trigger the workflow on pull request
+  pull_request:
+    # Selected branches
+    branches: [master, develop]
   # Trigger the workflow on push
   push:
     # Selected branches
-    branches: [master, develop, docs, patch]
+    branches: [master, develop]
     # Runs on creating a new tag starting with 'v', e.g. 'v1.0.3'
-    tags:
-      - 'v*'
+    tags: ['v*']
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
@@ -41,7 +60,7 @@ jobs:
 
     steps:
       - name: Check-out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0 # full history + tags. needed to get the latest release version
 
@@ -92,6 +111,12 @@ jobs:
       - name: Convert tutorial scripts to notebooks
         run: pixi run notebook-prepare
 
+      # The following step is needed to avoid the following message during the build:
+      # "Matplotlib is building the font cache; this may take a moment"
+      - name: Pre-build site step
+        run: pixi run python -c "import easydiffraction"
+
+      # Run the notebooks to generate the output cells using multiple cores
       - name: Run notebooks
         run: pixi run notebook-exec
 
@@ -121,26 +146,15 @@ jobs:
       # Upload the static files from the site/ directory to be used in the next job
       # This artifact is named github-pages and is a single gzip archive containing a single tar file
       # The artifact is then used in the next job by actions/deploy-pages to deploy the static files to GitHub Pages
-      # Unfortunately, the artifact is not available for download, so extra steps below are needed to do similar things
-      - name: Upload built site as artifact for DEV deployment (all branches)
+      # It can also be downloaded using the actions/download-artifact, as the current upload-pages-artifact
+      # is a wrapper which triggers the actions/upload-artifact.
+      - name: Upload built site as artifact
         uses: actions/upload-pages-artifact@v3
         with:
           path: site/
 
-      # Upload the static files from the site/ directory to be used in the next job
-      # This artifact is only uploaded on tagged releases (tags starting with 'v', e.g., v1.0.3)
-      # and is used to push content to gh_pages for custom domain deployment.
-      - name: Upload built site as artifact for PROD deployment (tagged release)
-        if: startsWith(github.ref, 'refs/tags/v')
-        uses: actions/upload-artifact@v4
-        with:
-          name: artifact # name of the artifact (without the extension zip)
-          path: site/
-          if-no-files-found: 'error'
-          compression-level: 0
-
-  # Job 2: Deploy the static files
-  deploy-docs:
+  # Job 2: Deploy the built static files to GitHub Pages (DEV deployment)
+  deploy-dev:
     needs: build-docs # previous job 'build-docs' need to be finished first
 
     # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
@@ -152,38 +166,59 @@ jobs:
     # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
     # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
     concurrency:
-      group: 'pages'
+      group: 'pages-dev'
       cancel-in-progress: false
 
     # Deploy to the github-pages environment
     environment:
-      name: github-pages # Artifact name
+      name: github-pages # Environment name
       url: ${{ steps.deployment.outputs.page_url }}
 
     runs-on: ubuntu-latest
 
+    # Triggered on push to develop or master branch only
+    if: ${{ github.ref_name == 'develop' || github.ref_name == 'master' }}
+
     steps:
       # Deploy the static files created in the previous job to GitHub Pages
       # To allow the deployment of the static files to GitHub Pages, no
       # restrictions on the branch name need to be set for desired branches on
       # https://github.com/easyscience/diffraction-lib/settings/environments
       # Deployed pages are available at https://easyscience.github.io/diffraction-lib
-      - name: DEV deployment (all branches)
+      - name: DEV deployment
         uses: actions/deploy-pages@v4
 
-      - name: Show DEV deployment url (all branches)
+      - name: Add DEV deployment url to summary
         run:
           echo "🔗 DEV deployment url [${{ env.DEV_DEPLOYMENT_URL }}](${{
           env.DEV_DEPLOYMENT_URL }})" >> $GITHUB_STEP_SUMMARY
 
+  # Job 3: Deploy the built static files to GitHub Pages (PROD deployment)
+  deploy-prod:
+    needs: deploy-dev # previous job 'deploy-dev' needs to be finished first
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      contents: read
+
+    # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+    # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+    concurrency:
+      group: 'pages-prod'
+      cancel-in-progress: false
+
+    runs-on: ubuntu-latest
+
+    # Triggered on tagged releases only (tags starting with 'v', e.g., v1.0.3)
+    if: startsWith(github.ref, 'refs/tags/v')
+
+    steps:
       # Download built site as artifact from a previous job for gh_pages (tagged release)
-      # This artifact is only downloaded on tagged releases (tags starting with 'v', e.g., v1.0.3)
-      # and is used to push content to gh_pages for custom domain deployment.
-      - name: Download built site from previous job (tagged release)
-        if: startsWith(github.ref, 'refs/tags/v')
+      # This artifact is used to push its content to gh_pages branch for custom domain deployment.
+      - name: Download built site from previous job
         uses: actions/download-artifact@v4
         with: # name or path are taken from the upload step of the previous job
-          name: artifact
+          name: github-pages
           path: site/ # directory to extract downloaded zipped artifacts
 
       # Push the site files created in the previous job to the gh_pages branch
@@ -196,16 +231,15 @@ jobs:
       # Then the gh_pages branch is used to deploy the site to the custom domain.
       # Deploying is done with a webhook added via:
       # https://github.com/easyscience/diffraction-lib/settings/hooks
-      - name: PROD deployment to gh_pages for custom domain (tagged release)
-        if: startsWith(github.ref, 'refs/tags/v')
+      - name: PROD deployment to gh_pages for custom domain
         uses: s0/git-publish-subdir-action@develop
         env:
           GITHUB_TOKEN: ${{ secrets.GH_API_PERSONAL_ACCSESS_TOKEN }}
           REPO: self
           BRANCH: gh_pages
           FOLDER: site
 
-      - name: Show PROD deployment url (tagged release)
+      - name: Show PROD deployment url
         if: startsWith(github.ref, 'refs/tags/v')
         run:
           echo "🔗 PROD deployment url [${{ env.PROD_DEPLOYMENT_URL }}](${{

.github/workflows/create-release-pr.yml

@@ -0,0 +1,35 @@
+# This workflow creates an automated release PR from `develop` into `master`.
+#
+# Usage:
+#   - Triggered manually via workflow_dispatch.
+#   - Creates a PR titled "Release: merge develop into master".
+#   - Adds the label "[maintainer] release" so it is excluded from changelogs.
+#   - The PR body makes clear that this is automation only (no review needed).
+
+name: Create release PR
+
+on:
+  workflow_dispatch: # manual trigger only
+
+jobs:
+  create-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Create PR from develop to master
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: develop
+          base: master
+          title: 'Release: merge develop into master'
+          body: |
+            This pull request is created automatically to trigger the release
+            pipeline. It merges the accumulated changes from `develop` into
+            `master`.
+
+            ⚠️ Note: This PR is labeled **[maintainer] release** and is excluded
+            from release notes and version bump logic.
+          labels: '[maintainer] release'
+          draft: false

.github/workflows/draft-release-notes.yml

@@ -7,6 +7,8 @@ on:
   # Runs on pushes targeting the default branch (updates the real draft release)
   push:
     branches: [master]
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
 
 jobs:
   draft-release-notes:
@@ -17,9 +19,34 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - name: Drafts the next release notes
-        uses: enhantica/drafterino@v1
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0 # full history with tags to get the version number by drafterino
+
+      - name: Set up pixi
+        uses: prefix-dev/[email protected]
+        with:
+          environments: >-
+            default
+          activate-environment: default
+          run-install: true
+          frozen: true
+          cache: false
+          post-cleanup: false
+
+      - name: Convert tutorial scripts to notebooks
+        run: pixi run notebook-prepare
+
+      - name: Clean up unnecessary script files
+        run: rm -rf tutorials/*.py
 
+      - name: Zip the tutorials directory
+        run: zip -9 -r tutorials.zip tutorials
+
+      - name: Drafts the next release notes
+        id: draft
+        uses: enhantica/drafterino@v2
         with:
           config: |
             title: 'easydiffraction $COMPUTED_VERSION'
@@ -43,3 +70,15 @@ jobs:
 
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create GitHub draft release
+        uses: softprops/action-gh-release@v2
+        with:
+          draft: true
+          tag_name: ${{ steps.draft.outputs.tag_name }}
+          name: ${{ steps.draft.outputs.release_name }}
+          body: ${{ steps.draft.outputs.release_notes }}
+          files: |
+            tutorials.zip
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/publish-pypi.yml

@@ -6,8 +6,7 @@ name: Publish to PyPI
 on:
   # Runs on creating a new tag starting with 'v', e.g. 'v1.0.3'
   push:
-    tags:
-      - 'v*'
+    tags: ['v*']
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
@@ -17,7 +16,7 @@ jobs:
 
     steps:
       - name: Check-out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: '0' # full history with tags to get the version number by versioningit
 

.github/workflows/scan-security.yml

@@ -7,8 +7,7 @@ name: Scan security (static analysis)
 on:
   # Trigger the workflow on pull request
   pull_request:
-    branches:
-      - '**'
+    branches: ['**']
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
@@ -20,7 +19,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           # We must fetch at least the immediate parents so that if this is
           # a pull request then we can checkout the head.