check_release_notes.yml

name: Check release notes
on:
  pull_request_target:
    types: [opened, synchronize, reopened, labeled, unlabeled]
    branches:
        - 'main'
        - 'release/*'
permissions:
  contents: read
  issues: write
  pull-requests: write
concurrency:
  group: release-notes-${{ github.event.pull_request.number }}
  cancel-in-progress: true
jobs:
  check_release_notes:
    permissions:
      contents: read
      issues: write
      pull-requests: write
    env:
      GH_TOKEN: ${{ github.token }}
      PR_AUTHOR: ${{ github.event.pull_request.user.login }}
      PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
      PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
      PR_LABELS: ${{ toJSON(github.event.pull_request.labels) }}
      PR_NUMBER: ${{ github.event.pull_request.number }}
      OPT_OUT_RELEASE_NOTES: ${{ contains(github.event.pull_request.labels.*.name, 'NO_RELEASE_NOTES') }}
      VNEXT: ${{ vars.VNEXT }}
    runs-on: ubuntu-latest
    steps:
    - name: Check for release notes changes
      id: release_notes_changes
      run: |
        set -euo pipefail
        EOF=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)
        FSHARP_REPO_URL="https://github.com/${GITHUB_REPOSITORY}"
        PR_URL="${FSHARP_REPO_URL}/pull/${PR_NUMBER}"

        [[ "$PR_BASE_SHA" =~ ^[0-9a-f]{40}$ ]] || { echo "::error::Unexpected base SHA: $PR_BASE_SHA"; exit 1; }
        [[ "$PR_HEAD_SHA" =~ ^[0-9a-f]{40}$ ]] || { echo "::error::Unexpected head SHA: $PR_HEAD_SHA"; exit 1; }

        echo "PR Tags: $PR_LABELS"
        echo "Opt out of release notes: $OPT_OUT_RELEASE_NOTES"

        _current_head_sha=$(gh api "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}" --jq '.head.sha')

        if [[ "$_current_head_sha" != "$PR_HEAD_SHA" ]]; then
          echo "::notice::Skipping stale release-note run for ${PR_HEAD_SHA}; current head is ${_current_head_sha}."
          exit 0
        fi

        # VNEXT is a GitHub repository variable set via admin settings
        # It controls the expected release notes version for FSharp.Core and FCS
        if [[ -z "$VNEXT" ]]; then
          echo "Error: VNEXT repository variable is not set. Please configure it in GitHub repository settings."
          exit 1
        fi

        # Parse VS major version from eng/Versions.props for the vNext pattern
        # <VSMajorVersion>18</VSMajorVersion>
        _versions_props=$(
          gh api \
            -H 'Accept: application/vnd.github.raw+json' \
            "repos/${GITHUB_REPOSITORY}/contents/eng/Versions.props?ref=${PR_BASE_SHA}"
        )
        _vs_major_version=$(
          sed -n 's:.*<VSMajorVersion>\([^<]*\)</VSMajorVersion>.*:\1:p' <<< "$_versions_props" \
            | head -n 1
        )

        FSHARP_CORE_VERSION="$VNEXT"
        VISUAL_STUDIO_VERSION="$_vs_major_version.vNext"

        echo "Using VNEXT for release notes: ${VNEXT}"
        echo "Visual Studio release notes: ${VISUAL_STUDIO_VERSION}"

        [[ "$VNEXT" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || (echo "  Invalid VNEXT format (expected X.Y.Z)"; exit 1)
        [[ "$_vs_major_version" =~ ^[0-9]+$ ]] || (echo "  Invalid VS major version parsed"; exit 1)

        _release_notes_base_path='docs/release-notes'
        _fsharp_core_release_notes_path="${_release_notes_base_path}/.FSharp.Core/${FSHARP_CORE_VERSION}.md"
        _fsharp_compiler_release_notes_path="${_release_notes_base_path}/.FSharp.Compiler.Service/${FSHARP_CORE_VERSION}.md"
        _fsharp_language_release_notes_path="${_release_notes_base_path}/.Language/preview.md"
        _fsharp_vs_release_notes_path="${_release_notes_base_path}/.VisualStudio/${VISUAL_STUDIO_VERSION}.md"

        readonly paths=(
            "src/FSharp.Core|${_fsharp_core_release_notes_path}"
            "src/Compiler|${_fsharp_compiler_release_notes_path}"
            "src/Compiler/Facilities/LanguageFeatures.fsi|${_fsharp_language_release_notes_path}"
            "vsintegration/src|${_fsharp_vs_release_notes_path}"
        )

        # Check all changed paths
        RELEASE_NOTES_MESSAGE=""
        RELEASE_NOTES_MESSAGE_DETAILS=""
        RELEASE_NOTES_FOUND=""
        RELEASE_NOTES_NOT_FOUND=""
        PULL_REQUEST_FOUND=true

        _modified_files=$(
          gh api \
            --method GET \
            --paginate \
            --slurp \
            "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files" \
            -f per_page=100
        )
        _modified_count=$(jq '[.[][]] | length' <<< "$_modified_files")

        # GitHub caps this endpoint at 3,000 files. At the cap the response may be
        # incomplete, so fail closed instead of silently missing a protected path.
        if (( _modified_count >= 3000 )); then
          echo "::error::Cannot safely validate a PR with 3,000 or more changed files."
          exit 1
        fi

        path_changed() {
          jq -e --arg path "$1" \
            'any(.[][]; .filename == $path or (.filename | startswith($path + "/")))' \
            <<< "$_modified_files" >/dev/null
        }

        release_note_url() {
          jq -r --arg file "$1" \
            'first(.[][] | select(.filename == $file and .status != "removed") | .contents_url) // empty' \
            <<< "$_modified_files"
        }

        record_missing_release_note() {
          local path="$1"
          local release_notes="$2"
          local description="**No release notes found or release notes format is not correct**"
          RELEASE_NOTES_NOT_FOUND+="| \\\`$path\\\` | [$release_notes](${FSHARP_REPO_URL}/tree/main/$release_notes) | ${description} |"
          RELEASE_NOTES_NOT_FOUND+=$'\n'
        }

        for fields in "${paths[@]}"; do
            IFS=$'|' read -r path release_notes <<< "$fields"
            echo "Checking for changed files in: $path"

            # Check if path is in modified files:
            if path_changed "$path"; then
                echo "  Found $path in modified files"
                echo "      Checking if release notes modified in: $release_notes"
                if path_changed "$release_notes"; then
                    echo "          Found $release_notes in modified files"
                    echo "              Checking for pull request URL in $release_notes"

                    _release_note_url=$(release_note_url "$release_notes")

                    if [[ -n "$_release_note_url" ]]; then
                        if [[ "$_release_note_url" != "https://api.github.com/repos/${GITHUB_REPOSITORY}/contents/"* ]] \
                          || [[ "$_release_note_url" != *"?ref=${PR_HEAD_SHA}" ]]; then
                          echo "::error::Release-note content URL does not target the expected repository and PR head."
                          exit 1
                        fi

                        _release_note_file=$(mktemp)

                        if ! gh api \
                          -H 'Accept: application/vnd.github.raw+json' \
                          "$_release_note_url" > "$_release_note_file"
                        then
                          rm -f "$_release_note_file"
                          echo "::error::Unable to read $release_notes at PR head $PR_HEAD_SHA."
                          exit 1
                        fi

                        _pr_link_occurrences=$(grep -Fc -- "$PR_URL" "$_release_note_file" || true)
                        rm -f "$_release_note_file"

                        echo "              Found $_pr_link_occurrences occurrences of $PR_URL in $release_notes"

                        if [[ ${_pr_link_occurrences} -eq 1 ]]; then
                            echo "                  Found pull request URL in $release_notes once"
                            RELEASE_NOTES_FOUND+="> | \\\`$path\\\` | [$release_notes](${FSHARP_REPO_URL}/tree/main/$release_notes) | |"
                            RELEASE_NOTES_FOUND+=$'\n'
                        elif [[ ${_pr_link_occurrences} -eq 0 ]]; then
                            echo "                  Did not find pull request URL in $release_notes"
                            DESCRIPTION="**No current pull request URL (${PR_URL}) found, please consider adding it**"
                            RELEASE_NOTES_FOUND+="> | \\\`$path\\\` | [$release_notes](${FSHARP_REPO_URL}/tree/main/$release_notes) | ${DESCRIPTION} |"
                            RELEASE_NOTES_FOUND+=$'\n'
                            PULL_REQUEST_FOUND=false
                        fi
                    else
                        echo "              $release_notes was removed or cannot be read at the PR head."
                        record_missing_release_note "$path" "$release_notes"
                    fi
                else
                    echo "          Did not find $release_notes in modified files"
                    record_missing_release_note "$path" "$release_notes"
                fi
            else
                echo "      Nothing found, no release notes required"
            fi
        done

        echo "Done checking for release notes changes"

        if [[ $RELEASE_NOTES_NOT_FOUND != "" ]]; then
            RELEASE_NOTES_MESSAGE_DETAILS+=$"@${PR_AUTHOR},"
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+=$"> [!CAUTION]"
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+=$"> **No release notes found for the changed paths (see table below).**"
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+=$">"
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+=$"> Please make sure to add an entry with an informative description of the change as well as link to this pull request, issue and language suggestion if applicable. Release notes for this repository are based on [Keep A Changelog](https://keepachangelog.com/en/1.1.0/) format."
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+=$">"
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+=$"> **The following format is recommended for this repository:**"
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+=$">"
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+=$">"
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+=$"> \\\`* <Informative description>. ([PR #XXXXX](https://github.com/dotnet/fsharp/pull/XXXXX))\\\`"
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+=$">"
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+=$">"
            RELEASE_NOTES_MESSAGE_DETAILS+=$"> See examples in the files, listed in the table below or in th full documentation at https://fsharp.github.io/fsharp-compiler-docs/release-notes/About.html."
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+=$'**If you believe that release notes are not necessary for this PR, please add <kbd>NO_RELEASE_NOTES</kbd> label to the pull request.**'
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+='| Change path      | Release notes path | Description |'
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+='| ---------------- | ------------------ | ----------- |'
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+="${RELEASE_NOTES_NOT_FOUND}"
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
        fi

        if [[ $RELEASE_NOTES_FOUND != "" ]]; then
            RELEASE_NOTES_MESSAGE_DETAILS+=$"<hr/>"
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+=$"> :white_check_mark: Found changes and release notes in following paths:"
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'

            if [[ $PULL_REQUEST_FOUND = false ]]; then
                RELEASE_NOTES_MESSAGE_DETAILS+=$"> [!WARNING]"
                RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
                RELEASE_NOTES_MESSAGE_DETAILS+=$"> **No PR link found in some release notes, please consider adding it.**"
                RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
                RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
                RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            fi

            RELEASE_NOTES_MESSAGE_DETAILS+='> | Change path      | Release notes path | Description |'
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+='> | ---------------- | ------------------ | ----------- |'
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
            RELEASE_NOTES_MESSAGE_DETAILS+="${RELEASE_NOTES_FOUND}"
            RELEASE_NOTES_MESSAGE_DETAILS+=$'\n'
        fi

        RELEASE_NOTES_MESSAGE+=$'<!-- DO_NOT_REMOVE: release_notes_check -->\n'

        if [[ $RELEASE_NOTES_MESSAGE_DETAILS == "" ]]; then
            RELEASE_NOTES_MESSAGE+=$'## :white_check_mark: No release notes required\n\n'
        else
            RELEASE_NOTES_MESSAGE+=$'## :heavy_exclamation_mark: Release notes required\n\n'
            RELEASE_NOTES_MESSAGE+=$"**You can open this PR in browser to add release notes: [open in github.dev](https://github.dev/dotnet/fsharp/pull/${PR_NUMBER})**"
            RELEASE_NOTES_MESSAGE+=$'\n\n'
            RELEASE_NOTES_MESSAGE+=$RELEASE_NOTES_MESSAGE_DETAILS
        fi

        _current_head_sha=$(gh api "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}" --jq '.head.sha')

        if [[ "$_current_head_sha" != "$PR_HEAD_SHA" ]]; then
          echo "::notice::Discarding stale release-note result for ${PR_HEAD_SHA}; current head is ${_current_head_sha}."
          exit 0
        fi

        {
            echo "release-notes-check-message<<$EOF"

            if [[ "$OPT_OUT_RELEASE_NOTES" = true ]]; then
                echo "<!-- DO_NOT_REMOVE: release_notes_check -->"
                echo ""
                echo "## :warning: Release notes required, but author opted out"
                echo ""
                echo ""
                echo "> [!WARNING]"
                echo "> **Author opted out of release notes, check is disabled for this pull request.**"
                echo "> cc @dotnet/fsharp-team-msft"
            else
                echo "${RELEASE_NOTES_MESSAGE}"
            fi

            echo "$EOF"
        } >> "$GITHUB_OUTPUT"

        if [[ $RELEASE_NOTES_NOT_FOUND != "" && ${OPT_OUT_RELEASE_NOTES} != true ]]; then
            exit 1
        fi
    # Keep one bot comment current without evaluating pull request content as JavaScript.
    # Posting the informational comment is best-effort and must never fail the check:
    # this job runs via pull_request_target, and the Actions GITHUB_TOKEN is not always
    # permitted to create a new issue comment (the comment API can return HTTP 403
    # "Resource not accessible by integration"), even though release-notes validation
    # above has already succeeded.
    - name: Create or update comment
      if: ${{ (success() || failure()) && steps.release_notes_changes.outputs.release-notes-check-message != '' }}
      continue-on-error: true
      uses: actions/github-script@v9
      env:
        COMMENT_BODY: ${{ steps.release_notes_changes.outputs.release-notes-check-message }}
      with:
        github-token: ${{ github.token }}
        script: |
            const marker = '<!-- DO_NOT_REMOVE: release_notes_check -->';
            try {
                const comments = await github.paginate(github.rest.issues.listComments, {
                    owner: context.repo.owner,
                    repo: context.repo.repo,
                    issue_number: context.issue.number,
                    per_page: 100
                });
                const existing = comments.find(comment =>
                    comment.user?.login === 'github-actions[bot]' && comment.body?.includes(marker));

                if (existing) {
                    const comment = await github.rest.issues.updateComment({
                        owner: context.repo.owner,
                        repo: context.repo.repo,
                        comment_id: existing.id,
                        body: process.env.COMMENT_BODY
                    });
                    return comment.data.id;
                }

                const comment = await github.rest.issues.createComment({
                    issue_number: context.issue.number,
                    owner: context.repo.owner,
                    repo: context.repo.repo,
                    body: process.env.COMMENT_BODY
                });
                return comment.data.id;
            } catch (error) {
                // The comment is informational only. The release-notes verdict is enforced by the
                // "Check for release notes changes" step, so never fail the job if posting fails
                // (e.g. a read-only token on some pull requests).
                core.warning(`Unable to post release-notes comment: ${error.message}`);
            }