Merge branch 'master' into patch-1

Author: skyace65

.github/ISSUE_TEMPLATE/bug_report.md

@@ -2,7 +2,7 @@
 name: Bug report
 about: Report incorrect or outdated documentation
 title: ''
-labels: bug
+labels: ''
 assignees: ''
 ---
 

.github/ISSUE_TEMPLATE/config.yml

@@ -4,3 +4,11 @@ contact_links:
   - name: Godot community channels
     url: https://godotengine.org/community
     about: Please ask for technical support on one of the other community channels, not here.
+
+  - name: Godot proposals
+    url: https://github.com/godotengine/godot-proposals
+    about: Please submit engine feature proposals on the Godot proposals repository, not here.
+
+  - name: Main Godot repository
+    url: https://github.com/godotengine/godot
+    about: Report engine bugs on the main Godot repository

.github/ISSUE_TEMPLATE/enhancement_request.md

@@ -2,7 +2,7 @@
 name: Enhancement request
 about: Suggest new documentation or improving existing documentation
 title: ''
-labels: enhancement
+labels: ''
 assignees: ''
 ---
 

.github/dependabot.yml

@@ -9,5 +9,7 @@ updates:
     schedule:
       interval: "daily"
     ignore:
-      # ReadTheDocs is staying on v1.
+      # We need to decide on when we upgrade Sphinx manually,
+      # as historically, this has been proven to often imply larger changes
+      # (RTD compat, upgrading extensions, other dependencies, our content, etc.).
       - dependency-name: "sphinx"

.github/workflows/build_offline_docs.yml

@@ -8,27 +8,55 @@ on:
 
 jobs:
   build:
-    runs-on: ubuntu-22.04
+    # Don't run scheduled runs on forks unless the CI_OFFLINE_DOCS_CRON variable is set to 'true'.
+    # Manual runs can still be triggered as normal.
+    if: ${{ github.repository_owner == 'godotengine' || github.event_name != 'schedule' || vars.CI_OFFLINE_DOCS_CRON == 'true' }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 180
     strategy:
+      max-parallel: 1
+      fail-fast: false
       matrix:
         branch:
           - master
           - stable
           - 3.6
+    permissions:
+      contents: write
     steps:
       - uses: actions/checkout@v4
         with:
           ref: ${{ matrix.branch }}
 
+      - name: Get Python version
+        id: pythonv
+        run: |
+          echo "PYTHON_VERSION=$(python --version)" >> $GITHUB_OUTPUT
+
+      - name: Restore cached virtualenv
+        uses: actions/cache/restore@v4
+        with:
+          key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }}
+          path: .venv
+
       - name: Install dependencies
         run: |
-          sudo pip3 install -r requirements.txt
-          sudo pip3 install codespell
+          python -m venv .venv
+          source .venv/bin/activate
+          python -m pip install -r requirements.txt
+          echo "$VIRTUAL_ENV/bin" >> $GITHUB_PATH
+          echo "VIRTUAL_ENV=$VIRTUAL_ENV" >> $GITHUB_ENV
           sudo apt update
-          sudo apt install parallel libwebp7
+          sudo apt install parallel libwebp7 imagemagick
+
+      - name: Save virtualenv cache
+        uses: actions/cache/save@v4
+        with:
+          key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }}
+          path: .venv
 
       - name: Sphinx - Build HTML
-        run: make SPHINXOPTS='--color' html
+        run: make SPHINXOPTS='--color -j 4' html
 
       - uses: actions/upload-artifact@v4
         with:
@@ -50,7 +78,7 @@ jobs:
           sed -i 's/"godot_is_latest": True/"godot_is_latest": False/' conf.py
           sed -i 's/"godot_show_article_status": True/"godot_show_article_status": False/' conf.py
 
-          make SPHINXOPTS='--color' epub
+          make SPHINXOPTS='--color -j 4' epub
 
       - uses: actions/upload-artifact@v4
         with:

.github/workflows/check_urls.yml

@@ -0,0 +1,36 @@
+name: 🌐 Check URLs
+on:
+  schedule:
+    # Every Friday at 16:27 UTC.
+    # URLs can decay over time. Setting up a schedule makes it possible to be warned
+    # about dead links as soon as possible.
+    - cron: "27 16 * * FRI"
+
+jobs:
+  check-urls:
+    runs-on: ubuntu-24.04
+    steps:
+
+      - uses: actions/checkout@v4
+
+      - name: Restore lychee cache
+        uses: actions/cache@v4
+        with:
+          path: .lycheecache
+          key: cache-lychee-${{ github.sha }}
+          restore-keys: cache-lychee-
+
+      - name: Run lychee
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >
+            --base .
+            --no-progress
+            --cache
+            --max-cache-age 1d
+            --exclude-path _templates/
+            --exclude-path classes/
+            "**/*.md" "**/*.html" "**/*.rst"
+
+      - name: Fail if there were link errors
+        run: exit ${{ steps.lc.outputs.exit_code }}

.github/workflows/cherrypick.yml

@@ -0,0 +1,75 @@
+name: Create Cherrypick PR
+
+on:
+  pull_request:
+      types:
+        - closed
+      branches:
+        # TODO: Extract this to an env variable?
+        - 'master'
+
+env:
+  # TODO: Add a way to handle multiple potential cherrypick targets.
+  TARGET_BRANCH: '4.3'
+  USERNAME: 'Godot Organization'
+  EMAIL: '[email protected]'
+
+jobs:
+  Create-cherrypick-PR:
+    # The cherrypick label is hardcoded because `contains()` doesn't seem to be able to use an environment variable as a second argument.
+    if: ${{ github.event.pull_request.merged == true && contains( github.event.pull_request.labels.*.name, 'cherrypick:4.3' ) }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    env:
+      # "Ternary" hack featured in the official docs.
+      # When using "Squash and merge", the commit hash is the last merge commit of the pull request merge branch.
+      # When using "Merge", the commit hash is the last commit to the head branch of the pull request.
+      # This is mildly error-prone, since in theory we could merge multiple commits without squashing.
+      # We are relying on human review of the generated PRs to catch that.
+      COMMIT_HASH: ${{ github.event.pull_request.commits > 1 && github.sha || github.event.pull_request.head.sha }}
+      PR_NUMBER: ${{ github.event.number }}
+
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        ref: ${{ env.TARGET_BRANCH }}
+
+    - name: Cherrypick Commit
+      id: cherrypick_commit
+      continue-on-error: true
+      # TODO: Maybe only fetch some branches?
+      run: |
+        git config user.name "${{ env.USERNAME }}"
+        git config user.email "${{ env.EMAIL }}"
+        git fetch
+        git cherry-pick -m 1 ${{ env.COMMIT_HASH }}
+
+    - name: Create Pull Request
+      if: steps.cherrypick_commit.outcome == 'success'
+      uses: peter-evans/create-pull-request@v7
+      with:
+        commit-message: 'Cherrypick to ${{ env.TARGET_BRANCH }}'
+        branch: 'cherrypick-${{ env.PR_NUMBER }}-${{ env.TARGET_BRANCH }}'
+        delete-branch: true
+
+        # Configure the commit author.
+        author: '${{ env.USERNAME }} <${{ env.EMAIL }}>'
+        committer: '${{ env.USERNAME }} <${{ env.EMAIL }}>'
+
+        # Configure the pull request.
+        title: 'Cherrypick ${{ env.PR_NUMBER }} to ${{ env.TARGET_BRANCH }}'
+        body: 'Cherrypick #${{ env.PR_NUMBER }} to ${{ env.TARGET_BRANCH }}.'
+        # TODO: Only add the bug or enhancement label, depending on which the original PR uses.
+        labels: 'bug,enhancement'
+
+    - name: Handle failure
+      if: steps.cherrypick_commit.outcome == 'failure'
+      run: |
+        echo "Can't automatically cherrypick. Potential causes:"
+        echo "- PR has multiple commits. Did you squash and merge?"
+        echo "- Cherrypick did not apply cleanly and can't be auto-merged."

.github/workflows/ci.yml

@@ -5,29 +5,47 @@ on:
   pull_request:
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref_name }}
   cancel-in-progress: true
 
 jobs:
   build:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
+    timeout-minutes: 120
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Install dependencies
+      - name: Style checks via pre-commit
+        uses: pre-commit/[email protected]
+
+      - name: Get Python version
+        id: pythonv
         run: |
-          # Install tools used by `_tools/format.sh`.
-          sudo apt-get -qq update
-          sudo apt-get -qq install dos2unix recode
-          sudo pip3 install -r requirements.txt
-          sudo pip3 install codespell
+          echo "PYTHON_VERSION=$(python --version)" >> $GITHUB_OUTPUT
+
+      - name: Restore cached virtualenv
+        uses: actions/cache/restore@v4
+        with:
+          key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }}
+          path: .venv
 
-      - name: Linter checks
+      - name: Install dependencies
         run: |
-          bash _tools/format.sh
-          codespell -I _tools/codespell-ignore.txt -x _tools/codespell-ignore-lines.txt -S tutorials/i18n/locales.rst {about,community,development,getting_started,tutorials}/**/*.rst
+          python -m venv .venv
+          source .venv/bin/activate
+          python -m pip install -r requirements.txt
+          echo "$VIRTUAL_ENV/bin" >> $GITHUB_PATH
+          echo "VIRTUAL_ENV=$VIRTUAL_ENV" >> $GITHUB_ENV
+
+      - name: Save virtualenv cache
+        uses: actions/cache/save@v4
+        with:
+          key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }}
+          path: .venv
 
       # Use dummy builder to improve performance as we don't need the generated HTML in this workflow.
       - name: Sphinx build
-        run: make SPHINXOPTS='--color -W' dummy
+        run: |
+          source .venv/bin/activate
+          make SPHINXOPTS='--color -j 4 -W' dummy

.github/workflows/sync_class_ref.yml

@@ -3,22 +3,30 @@ name: Sync Class Reference
 on:
   workflow_dispatch:
   # Scheduled updates only run on the default/master branch.
+  # Other branches need to be run manually (usually after a new release for that branch).
   schedule:
-    # Run it at night (European time) every Saturday.
-    # The offset is there to try and avoid the high load times.
+    # Run it at (European) night time every Saturday.
+    # The offset is there to try and avoid high load times.
     - cron: '15 3 * * 6'
 
 # Make sure jobs cannot overlap.
 concurrency:
-  group: classref-sync-ci-master
+  group: classref-sync-ci-${{ github.ref_name }}
   cancel-in-progress: true
 
 jobs:
   build:
+    # Don't run scheduled runs on forks unless the CI_SYNC_CLASS_REF_CRON variable is set to 'true'.
+    # Manual runs can still be triggered as normal.
+    if: ${{ github.repository_owner == 'godotengine' || github.event_name != 'schedule' || vars.CI_SYNC_CLASS_REF_CRON == 'true' }}
     name: Update class reference files based on the engine revision
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
     env:
       engine_rev: 'master'
+    permissions:
+      contents: write
+      pull-requests: write
 
     steps:
       - name: Checkout the documentation repository
@@ -51,7 +59,7 @@ jobs:
           ./.engine-src/doc/tools/make_rst.py --color -o ./classes -l en ./.engine-src/doc/classes ./.engine-src/modules ./.engine-src/platform
 
       - name: Submit a pull-request
-        uses: peter-evans/create-pull-request@v6
+        uses: peter-evans/create-pull-request@v7
         with:
           commit-message: 'classref: Sync with current ${{ env.engine_rev }} branch (${{ steps.engine.outputs.rev_hash_short }})'
           branch: 'classref/sync-${{ steps.engine.outputs.rev_hash_short }}'

.gitignore

@@ -3,15 +3,29 @@
 .env
 
 _build/
-env/
-__pycache__
-*.pyc
 *~
 .directory
 .vs/
 .vscode/
 *.mo
 
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Common environment files
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# User created Python virtual environment as described in the docs
+godot-docs-venv/
+
 # Vim temp files
 *.swo
 *.swp
@@ -45,8 +59,5 @@ logo.h
 tmp-unused-images
 tmp-unused-images-history
 
-# User created Python virtual environement as described in the docs
-godot-docs-venv/
-
 # Jetbrains IDE files
 /.idea/