[pull] master from godotengine:master

.github/ISSUE_TEMPLATE/bug_report.md

@@ -2,7 +2,7 @@
 name: Bug report
 about: Report incorrect or outdated documentation
 title: ''
-labels: bug
+labels: ''
 assignees: ''
 ---
 
@@ -11,3 +11,9 @@ assignees: ''
 **Issue description:**
 
 **URL to the documentation page:**
+
+If you know how to fix the issue you are reporting please
+consider opening a pull request. We provide a tutorial on
+using git here: https://contributing.godotengine.org/en/latest/organization/pull_requests/creating_pull_requests.html,
+writing documentation at https://contributing.godotengine.org/en/latest/documentation/guidelines/index.html
+and contributing to the class reference here: https://contributing.godotengine.org/en/latest/documentation/class_reference.html

.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/PULL_REQUEST_TEMPLATE.md

@@ -1,8 +1,8 @@
 <!--
-**Note:** Pull Requests should be made against the `master` by default.
-
-Only make Pull Requests against other branches (e.g. `2.1`) if your changes only apply to that specific version of Godot.
-
-The type of content accepted into the documentation is explained here: https://docs.godotengine.org/en/latest/community/contributing/content_guidelines.html
+Please target the `master` branch in priority.
+PRs can target other branches (e.g. `3.2`, `3.5`) if the same change was done in `master`, or is not relevant there.
+PRs must not target `stable`, as that branch is updated manually.
 
+The type of content accepted into the documentation is explained here:
+https://contributing.godotengine.org/en/latest/documentation/guidelines/content_guidelines.html
 -->

.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

@@ -1,31 +1,89 @@
 name: Build documentation for offline usage
 on:
+  workflow_dispatch:
   schedule:
     # Every week on Monday at midnight (UTC).
     # This keeps the generated HTML documentation fresh.
     - cron: '0 0 * * 1'
 
 jobs:
   build:
-    runs-on: ubuntu-20.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:
-      - name: Checkout
-        uses: actions/checkout@v2
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ matrix.branch }}
 
-      - name: Install dependencies
+      - name: Get Python version
+        id: pythonv
         run: |
-          sudo pip3 install -r requirements.txt
-          sudo pip3 install codespell
+          echo "PYTHON_VERSION=$(python --version)" >> $GITHUB_OUTPUT
 
-      # Build the HTML to upload it.
-      - name: Sphinx build
+      - name: Restore cached virtualenv
+        uses: actions/cache/restore@v5
+        with:
+          key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }}
+          path: .venv
+
+      - name: Install dependencies
         run: |
-          sphinx-build --color -d _build/doctrees -W . _build/html
+          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 imagemagick
 
-      - uses: actions/upload-artifact@v2
+      - name: Save virtualenv cache
+        uses: actions/cache/save@v5
         with:
-          name: godot-docs-html
+          key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }}
+          path: .venv
+
+      - name: Sphinx - Build HTML
+        run: make SPHINXOPTS='--color -j 4' html
+
+      - uses: actions/upload-artifact@v6
+        with:
+          name: godot-docs-html-${{ matrix.branch }}
           path: _build/html
           # Keep the current build and the previous build (in case a scheduled build failed).
           # This makes it more likely to have at least one successful build available at all times.
           retention-days: 15
+
+      - name: Sphinx - Build ePub
+        run: |
+          # Convert WebP images to PNG and replace references, so that ePub readers can display those images.
+          # The ePub 3.0 specification has WebP support, but it's not widely supported by apps and e-readers yet.
+          shopt -s globstar nullglob
+          parallel --will-cite convert {} {.}.png ::: {about,community,contributing,getting_started,img,tutorials}/**/*.webp
+          parallel --will-cite sed -i "s/\\.webp$/\\.png/g" ::: {about,community,contributing,getting_started,tutorials}/**/*.rst
+
+          # Remove banners at the top of each page when building `latest`.
+          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 -j 4' epub
+
+      - uses: actions/upload-artifact@v6
+        with:
+          name: godot-docs-epub-${{ matrix.branch }}
+          path: _build/epub/GodotEngine.epub
+          # Keep the current build and the previous build (in case a scheduled build failed).
+          # This makes it more likely to have at least one successful build available at all times.
+          retention-days: 15

.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@v6
+
+      - name: Restore lychee cache
+        uses: actions/cache@v5
+        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: 'noreply@godotengine.org'
+
+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@v6
+      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@v8
+      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

@@ -1,29 +1,55 @@
 name: Continuous integration
+
 on:
   push:
   pull_request:
 
+concurrency:
+  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@v2
+        uses: actions/checkout@v6
 
-      - name: Install dependencies
+      - name: Style checks via pre-commit
+        uses: pre-commit/action@v3.0.1
+
+      - name: Custom RST checks (check-rst.sh)
         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
+          bash ./_tools/check-rst.sh
 
-      - name: Linter checks
+      - name: Get Python version
+        id: pythonv
         run: |
-          bash _tools/format.sh
-          codespell -I _tools/codespell-ignore.txt -x _tools/codespell-ignore-lines.txt {about,community,development,getting_started,tutorials}/**/*.rst
+          echo "PYTHON_VERSION=$(python --version)" >> $GITHUB_OUTPUT
+
+      - name: Restore cached virtualenv
+        uses: actions/cache/restore@v5
+        with:
+          key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }}
+          path: .venv
+
+      - name: Install dependencies
+        run: |
+          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@v5
+        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: |
-          sphinx-build --color -b dummy -d _build/doctrees -W . _build/html
+          source .venv/bin/activate
+          make SPHINXOPTS='--color -j 4 -W' dummy