Merge branch 'master' into mlum

.git-blame-ignore-revs

@@ -0,0 +1 @@
+# .git-blame-ignore-revs

.github/contributing.md

@@ -94,11 +94,39 @@ in next Skript release, whenever that happens.
 
 Good luck!
 
-### Pull Request Review
-Pull requests require one passing review before they can be merged. In
-addition to that, code submitted by people outside of core team must be tested
-by core team members. In some cases, this might be as simple as running the
-automated tests.
-
-In exceptional situations, pull requests may be merged regardless of review
-status by @bensku.
+### Submitting a Contribution
+
+Having submitted your contribution it will enter a public review phase.
+
+Other contributors and users may make comments or ask questions about your contribution. \
+You are encouraged to respond to these - people may have valuable feedback!
+
+Developers may request changes to the content of your pull request. These are valuable since they may concern unreleased content. Please respect our team's wishes - changes are requested when we see room for improvement or necessary issues that need to be addressed.
+Change requests are not an indictment of your code quality.
+
+Developers may also request changes to the formatting of your code and attached files. These are important to help maintain the consistent standard and readability of our code base.
+
+Once you have made the requested changes (or if you require clarification or assistance) you can request a re-review from the developer.
+
+You don't need to keep your pull request fork up-to-date with Skript's master branch - we can update it automatically and notify you if there are any problems.
+
+### Merging a Contribution
+
+Pull requests may be left un-merged until an appropriate time (e.g. before a suitable release.) This timeframe may be increased for breaking changes or significant new features, which might be better targeted in a major version.
+
+Please respect the process - this is a very complex project that takes a lot of time and care to maintain. Your contribution has not been forgotten about.
+
+For a contribution to be merged it requires at least two approving reviews from the core development team. It will then require a senior member to merge it.
+
+You do not need to 'bump' your contribution if it is un-merged; we may be waiting for a more suitable release to include it.
+
+If you have been waiting for a response to a question or change for a significant time please re-request our reviews or contact us.
+
+In exceptional situations, pull requests may be merged regardless of review status by one of the organisation admins. 
+
+### Peaceful Resolution
+
+Please respect our maintainers, developers, contributors and users. \
+Our contributors come from a wide variety of backgrounds and countries - you may need to explain issues and requests if they are misunderstood.
+
+Please refer disrespectful and unpleasant behaviour to our tracker team. For concerns about abuse, please contact the organisation directly.

.github/dependabot.yml

@@ -1,11 +1,17 @@
 version: 2
 updates:
-- package-ecosystem: "github-actions"
-  directory: "/"
-  schedule:
-    interval: "daily"
-- package-ecosystem: gradle
-  directory: "/"
-  schedule:
-    interval: daily
-  open-pull-requests-limit: 10
+  - package-ecosystem: "github-actions"
+    target-branch: "dev/patch"
+    directory: "/"
+    schedule:
+        interval: "weekly"
+    labels:
+      - "dependencies"
+  - package-ecosystem: "gradle"
+    target-branch: "dev/patch"
+    directory: "/"
+    schedule:
+        interval: "weekly"
+    labels:
+      - "dependencies"
+    open-pull-requests-limit: 10

.github/pull_request_template.md

@@ -2,6 +2,6 @@
 <!--- Describe your changes here. --->
 
 ---
-**Target Minecraft Versions:** <!-- 'any' means all supported versions -->
-**Requirements:** <!-- Required plugins, Minecraft versions, server software... -->
-**Related Issues:** <!-- Links to related issues -->
+**Target Minecraft Versions:** any <!-- 'any' means all supported versions -->
+**Requirements:** none <!-- Required plugins, server software... -->
+**Related Issues:** none <!-- Links to related issues -->

.github/workflows/cleanup-docs.yml

@@ -0,0 +1,39 @@
+name: Cleanup nightly documentation
+on: delete
+jobs:
+  cleanup-nightly-docs:
+    if: github.event.ref_type == 'branch'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Configure workflow
+        id: configuration
+        env:
+          DELETED_BRANCH: ${{ github.event.ref }}
+        run: |
+          BRANCH_NAME="${DELETED_BRANCH#refs/*/}"
+          echo "BRANCH_NAME=${BRANCH_NAME}" >> $GITHUB_OUTPUT
+          echo "DOCS_OUTPUT_DIR=${GITHUB_WORKSPACE}/skript-docs/docs/nightly/${BRANCH_NAME}" >> $GITHUB_OUTPUT
+          echo "DOCS_REPO_DIR=${GITHUB_WORKSPACE}/skript-docs" >> $GITHUB_OUTPUT
+      - name: Checkout Skript
+        uses: actions/checkout@v4
+        with:
+            ref: ${{ github.event.repository.default_branch }}
+            submodules: recursive
+            path: skript
+      - name: Setup documentation environment
+        uses: ./skript/.github/workflows/docs/setup-docs
+        with:
+            docs_deploy_key: ${{ secrets.DOCS_DEPLOY_KEY }}
+            docs_output_dir: ${{ steps.configuration.outputs.DOCS_OUTPUT_DIR }}
+      - name: Cleanup nightly documentation
+        env:
+          DOCS_OUTPUT_DIR: ${{ steps.configuration.outputs.DOCS_OUTPUT_DIR }}
+        run: |
+          rm -rf ${DOCS_OUTPUT_DIR} || true
+      - name: Push nightly documentation cleanup
+        uses: ./skript/.github/workflows/docs/push-docs
+        with:
+            docs_repo_dir: ${{ steps.configuration.outputs.DOCS_REPO_DIR }}
+            git_name: Nightly Docs Bot
+            git_email: nightlydocs@skriptlang.org
+            git_commit_message: "Delete ${{ steps.configuration.outputs.BRANCH_NAME }} branch nightly docs"

.github/workflows/docs/generate-docs/action.yml

@@ -0,0 +1,109 @@
+name: Generate documentation
+
+inputs:
+  docs_output_dir:
+    description: "The directory to generate the documentation into"
+    required: true
+    type: string
+  docs_repo_dir:
+    description: "The skript-docs repository directory"
+    required: true
+    type: string
+  skript_repo_dir:
+    description: "The skript repository directory"
+    required: true
+    type: string
+  is_release:
+    description: "Designates whether to generate nightly or release documentation"
+    required: false
+    default: false
+    type: boolean
+  cleanup_pattern:
+    description: "A pattern designating which files to delete when cleaning the documentation output directory"
+    required: false
+    default: "*"
+    type: string
+  generate_javadocs:
+    description: "Designates whether to generate javadocs for this nightly documentation"
+    required: false
+    default: false
+    type: boolean
+
+outputs:
+  DOCS_CHANGED:
+    description: "Whether or not the documentation has changed since the last push"
+    value: ${{ steps.generate.outputs.DOCS_CHANGED }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: generate-docs
+      id: generate
+      shell: bash
+      env:
+        DOCS_OUTPUT_DIR: ${{ inputs.docs_output_dir }}
+        DOCS_REPO_DIR: ${{ inputs.docs_repo_dir }}
+        SKRIPT_REPO_DIR: ${{ inputs.skript_repo_dir }}
+        IS_RELEASE: ${{ inputs.is_release }}
+        CLEANUP_PATTERN: ${{ inputs.cleanup_pattern }}
+        GENERATE_JAVADOCS: ${{ inputs.generate_javadocs }}
+      run: |
+        replace_in_directory() {
+          find $1 -type f -exec sed -i -e "s/$2/$3/g" {} \;
+        }
+
+        # this should be replaced with a more reliable jq command,
+        # but it can't be right now because docs.json is actually not valid json.
+        get_skript_version_of_directory() {
+          grep skriptVersion "$1/docs.json" | cut -d\" -f 4
+        }
+
+        if [ -d "${DOCS_REPO_DIR}/docs/templates" ]
+        then
+          export SKRIPT_DOCS_TEMPLATE_DIR=${DOCS_REPO_DIR}/docs/templates
+        else # compatibility for older versions
+          export SKRIPT_DOCS_TEMPLATE_DIR=${DOCS_REPO_DIR}/doc-templates
+        fi
+
+        export SKRIPT_DOCS_OUTPUT_DIR=/tmp/generated-docs
+                  
+        cd $SKRIPT_REPO_DIR
+        if [[ "${IS_RELEASE}" == "true" ]]; then
+          ./gradlew genReleaseDocs releaseJavadoc
+        elif [[ "${GENERATE_JAVADOCS}" == "true" ]]; then
+          ./gradlew genNightlyDocs javadoc
+        else
+          ./gradlew genNightlyDocs
+        fi
+
+        if [ -d "${DOCS_OUTPUT_DIR}" ]; then
+          if [[ "${GENERATE_JAVADOCS}" == "true" ]]; then
+              mkdir -p "${SKRIPT_DOCS_OUTPUT_DIR}/javadocs" && cp -a "./build/docs/javadoc/." "$_"
+          fi
+  
+          mkdir -p "/tmp/normalized-output-docs" && cp -a "${DOCS_OUTPUT_DIR}/." "$_"
+          mkdir -p "/tmp/normalized-generated-docs" && cp -a "${SKRIPT_DOCS_OUTPUT_DIR}/." "$_"
+
+          output_skript_version=$(get_skript_version_of_directory "/tmp/normalized-output-docs")
+          generated_skript_version=$(get_skript_version_of_directory "/tmp/normalized-generated-docs")
+
+          replace_in_directory "/tmp/normalized-output-docs" "${output_skript_version}" "Skript"
+          replace_in_directory "/tmp/normalized-generated-docs" "${generated_skript_version}" "Skript"
+
+          diff -qbr /tmp/normalized-output-docs /tmp/normalized-generated-docs || diff_exit_code=$?
+          # If diff exits with exit code 1, that means there were some differences
+          if [[ ${diff_exit_code} -eq 1 ]]; then
+            echo "DOCS_CHANGED=true" >> $GITHUB_OUTPUT
+            echo "Documentation has changed since last push"
+          else
+            echo "Documentation hasn't changed since last push"
+          fi
+        else
+            echo "DOCS_CHANGED=true" >> $GITHUB_OUTPUT
+            echo "No existing documentation found"
+        fi
+
+        rm -rf ${DOCS_OUTPUT_DIR}/${CLEANUP_PATTERN} || true
+        mkdir -p "${DOCS_OUTPUT_DIR}/" && cp -a "${SKRIPT_DOCS_OUTPUT_DIR}/." "$_"
+
+

.github/workflows/docs/push-docs/action.yml

@@ -0,0 +1,43 @@
+name: Push documentation
+
+inputs:
+  docs_repo_dir:
+    description: "The skript-docs repository directory"
+    required: true
+    type: string
+  git_email:
+    description: "The email to use for the Git commit"
+    required: true
+    type: string
+  git_name:
+    description: "The name to use for the Git commit"
+    required: true
+    type: string
+  git_commit_message:
+    description: "The message to use for the Git commit"
+    required: true
+    type: string
+
+runs:
+  using: 'composite'
+  steps:
+    - shell: bash
+      if: success()
+      env:
+        DOCS_REPO_DIR: ${{ inputs.docs_repo_dir }}
+        GIT_EMAIL: ${{ inputs.git_email }}
+        GIT_NAME: ${{ inputs.git_name }}
+        GIT_COMMIT_MESSAGE: ${{ inputs.git_commit_message }}
+      run: |
+        cd "${DOCS_REPO_DIR}"
+        git config user.name "${GIT_NAME}"
+        git config user.email "${GIT_EMAIL}"
+        git add -A
+        git commit -m "${GIT_COMMIT_MESSAGE}" || (echo "Nothing to push!" && exit 0)
+        # Attempt rebasing and pushing 5 times in case another job pushes before us
+        for i in 1 2 3 4 5
+        do
+          git pull --rebase -X theirs origin main
+          git push origin main && break
+          sleep 5
+        done

.github/workflows/docs/setup-docs/action.yml

@@ -0,0 +1,43 @@
+name: Setup documentation environment
+
+inputs:
+  docs_deploy_key: 
+    description: "Deploy key for the skript-docs repo"
+    required: true
+    type: string
+  docs_output_dir:
+    description: "The directory to generate the documentation into"
+    required: true
+    type: string
+  cleanup_pattern:
+    description: "A pattern designating which files to delete when cleaning the documentation output directory"
+    required: false
+    default: "*"
+    type: string
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Checkout skript-docs
+      uses: actions/checkout@v3
+      with:
+        repository: 'SkriptLang/skript-docs'
+        path: skript-docs
+        ssh-key: ${{ inputs.docs_deploy_key }}
+    - uses: actions/setup-java@v3
+      with:
+        java-version: '17'
+        distribution: 'adopt'
+        cache: gradle
+    - shell: bash
+      run: chmod +x ./skript/gradlew
+    - shell: bash
+      env:
+        DOCS_DEPLOY_KEY: ${{ inputs.docs_deploy_key }}
+        DOCS_OUTPUT_DIR: ${{ inputs.docs_output_dir }}
+        CLEANUP_PATTERN: ${{ inputs.cleanup_pattern }}
+      run: |
+        eval `ssh-agent`
+        echo "$DOCS_DEPLOY_KEY" | tr -d '\r' | ssh-add - > /dev/null
+        mkdir ~/.ssh
+        ssh-keyscan www.github.com >> ~/.ssh/known_hosts

.github/workflows/java-17-builds.yml

@@ -5,15 +5,18 @@ on:
         branches:
             - master
             - 'dev/**'
+    pull_request:
 
 jobs:
     build:
         if: "! contains(toJSON(github.event.commits.*.message), '[ci skip]')"
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v3
+            - uses: actions/checkout@v4
               with:
                   submodules: recursive
+            - name: validate gradle wrapper
+              uses: gradle/wrapper-validation-action@v2
             - name: Set up JDK 17
               uses: actions/setup-java@v3
               with:
@@ -22,12 +25,10 @@ jobs:
                   cache: gradle
             - name: Grant execute permission for gradlew
               run: chmod +x gradlew
-            - name: Build Skript
-              run: ./gradlew nightlyRelease
-            - name: Run test scripts
+            - name: Build Skript and run test scripts
               run: ./gradlew clean skriptTestJava17
             - name: Upload Nightly Build
-              uses: actions/upload-artifact@v3
+              uses: actions/upload-artifact@v4
               if: success()
               with:
                   name: skript-nightly

.github/workflows/java-8-builds.yml

@@ -5,29 +5,30 @@ on:
         branches:
             - master
             - 'dev/**'
+    pull_request:
 
 jobs:
     build:
         if: "! contains(toJSON(github.event.commits.*.message), '[ci skip]')"
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v3
+            - uses: actions/checkout@v4
               with:
                   submodules: recursive
+            - name: validate gradle wrapper
+              uses: gradle/wrapper-validation-action@v2
             - name: Set up JDK 17
-              uses: actions/setup-java@v3
+              uses: actions/setup-java@v4
               with:
                   java-version: '17'
                   distribution: 'adopt'
                   cache: gradle
             - name: Grant execute permission for gradlew
               run: chmod +x gradlew
-            - name: Build Skript
-              run: ./gradlew nightlyRelease
-            - name: Run test scripts
+            - name: Build Skript and run test scripts
               run: ./gradlew clean skriptTestJava8
             - name: Upload Nightly Build
-              uses: actions/upload-artifact@v3
+              uses: actions/upload-artifact@v4
               if: success()
               with:
                   name: skript-nightly