Merge branch 'master' into waagent-module

.github/ISSUE_TEMPLATE/tracking_issue.md

@@ -0,0 +1,39 @@
+---
+name: Tracking issue
+about: Provide an overview on a multi-step effort
+title: 'Tracking issue: ISSUENAME'
+labels: '5.scope: tracking'
+assignees: ''
+
+---
+
+### Tracking description
+
+<!--
+Provide a brief summary of the project or multi-step effort. Explain why it is
+necessary and what the goals are.
+
+You may include way to reproduce the problem, screenshots or any information
+that you find relevant.
+-->
+
+#### Reference Issue(s)/PR(s)
+
+- ...
+
+### Follow-up issues/notes
+
+<!--
+List any follow-up issues that need to be addressed after the main tasks are
+completed, or any notes related to the project.
+-->
+
+#### Additional context
+Add any other context about the problem here.
+
+---
+
+Add a :+1: [reaction] to [issues you find important].
+
+[reaction]: https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/
+[issues you find important]: https://github.com/NixOS/nixpkgs/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc

.github/workflows/check-nix-format.yml

@@ -83,7 +83,7 @@ jobs:
 
           if (( "${#unformattedFiles[@]}" > 0 )); then
             echo "Some new/changed Nix files are not properly formatted"
-            echo "Please go to the Nixpkgs root directory, run \`nix-shell\`, then:"
+            echo "Please format them using the Nixpkgs-specific \`nixfmt\` by going to the Nixpkgs root directory, running \`nix-shell\`, then:"
             echo "nixfmt ${unformattedFiles[*]@Q}"
             echo "Make sure your branch is up to date with master, rebase if not."
             echo "If you're having trouble, please ping @NixOS/nix-formatting"

.github/workflows/eval.yml

@@ -16,72 +16,48 @@ permissions:
   contents: read
 
 jobs:
+  get-merge-commit:
+    uses: ./.github/workflows/get-merge-commit.yml
+
   attrs:
     name: Attributes
     runs-on: ubuntu-latest
+    needs: get-merge-commit
     outputs:
-      mergedSha: ${{ steps.merged.outputs.mergedSha }}
+      mergedSha: ${{ needs.get-merge-commit.outputs.mergedSha }}
       baseSha: ${{ steps.baseSha.outputs.baseSha }}
       systems: ${{ steps.systems.outputs.systems }}
     steps:
-      # Important: Because of `pull_request_target`, this doesn't check out the PR,
-      # but rather the base branch of the PR, which is needed so we don't run untrusted code
-      - name: Check out the ci directory of the base branch
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          path: base
-          sparse-checkout: ci
-      - name: Check if the PR can be merged and get the test merge commit
-        id: merged
-        env:
-          GH_TOKEN: ${{ github.token }}
-          GH_EVENT: ${{ github.event_name }}
-        run: |
-          case "$GH_EVENT" in
-            push)
-              echo "mergedSha=${{ github.sha }}" >> "$GITHUB_OUTPUT"
-              ;;
-            pull_request_target)
-              if mergedSha=$(base/ci/get-merge-commit.sh ${{ github.repository }} ${{ github.event.number }}); then
-                echo "Checking the merge commit $mergedSha"
-                echo "mergedSha=$mergedSha" >> "$GITHUB_OUTPUT"
-              else
-                # Skipping so that no notifications are sent
-                echo "Skipping the rest..."
-              fi
-              ;;
-          esac
-          rm -rf base
       - name: Check out the PR at the test merge commit
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         # Add this to _all_ subsequent steps to skip them
-        if: steps.merged.outputs.mergedSha
+        if: needs.get-merge-commit.outputs.mergedSha
         with:
-          ref: ${{ steps.merged.outputs.mergedSha }}
+          ref: ${{ needs.get-merge-commit.outputs.mergedSha }}
           fetch-depth: 2
           path: nixpkgs
 
       - name: Determine base commit
-        if: github.event_name == 'pull_request_target' && steps.merged.outputs.mergedSha
+        if: github.event_name == 'pull_request_target' && needs.get-merge-commit.outputs.mergedSha
         id: baseSha
         run: |
           baseSha=$(git -C nixpkgs rev-parse HEAD^1)
           echo "baseSha=$baseSha" >> "$GITHUB_OUTPUT"
 
       - name: Install Nix
         uses: cachix/install-nix-action@08dcb3a5e62fa31e2da3d490afc4176ef55ecd72 # v30
-        if: steps.merged.outputs.mergedSha
+        if: needs.get-merge-commit.outputs.mergedSha
 
       - name: Evaluate the list of all attributes and get the systems matrix
         id: systems
-        if: steps.merged.outputs.mergedSha
+        if: needs.get-merge-commit.outputs.mergedSha
         run: |
           nix-build nixpkgs/ci -A eval.attrpathsSuperset
           echo "systems=$(<result/systems.json)" >> "$GITHUB_OUTPUT"
 
       - name: Upload the list of all attributes
         uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.4.3
-        if: steps.merged.outputs.mergedSha
+        if: needs.get-merge-commit.outputs.mergedSha
         with:
           name: paths
           path: result/*
@@ -246,6 +222,7 @@ jobs:
     if: needs.process.outputs.baseRunId
     permissions:
       pull-requests: write
+      statuses: write
     steps:
       - name: Download process result
         uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
@@ -285,3 +262,23 @@ jobs:
           GH_TOKEN: ${{ github.token }}
           REPOSITORY: ${{ github.repository }}
           NUMBER: ${{ github.event.number }}
+
+      - name: Add eval summary to commit statuses
+        if: ${{ github.event_name == 'pull_request_target' }}
+        run: |
+          description=$(jq -r '
+          "Package: added " + (.attrdiff.added | length | tostring) +
+          ", removed " + (.attrdiff.removed | length | tostring) +
+          ", changed " + (.attrdiff.changed | length | tostring) +
+          ", Rebuild: linux " + (.rebuildCountByKernel.linux | tostring) +
+          ", darwin " + (.rebuildCountByKernel.darwin | tostring)
+          ' <comparison/changed-paths.json)
+          target_url="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID?pr=$NUMBER"
+          gh api --method POST \
+            -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" \
+            "/repos/$GITHUB_REPOSITORY/statuses/$PR_HEAD_SHA" \
+            -f "context=Eval / Summary" -f "state=success" -f "description=$description" -f "target_url=$target_url"
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          NUMBER: ${{ github.event.number }}

.github/workflows/get-merge-commit.yml

@@ -0,0 +1,43 @@
+name: Get merge commit
+
+on:
+  workflow_call:
+    outputs:
+      mergedSha:
+        description: "The merge commit SHA"
+        value: ${{ jobs.resolve-merge-commit.outputs.mergedSha }}
+
+# We need a token to query the API, but it doesn't need any special permissions
+permissions: {}
+
+jobs:
+  resolve-merge-commit:
+    runs-on: ubuntu-latest
+    outputs:
+      mergedSha: ${{ steps.merged.outputs.mergedSha }}
+    steps:
+    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      with:
+        path: base
+        sparse-checkout: ci
+    - name: Check if the PR can be merged and get the test merge commit
+      id: merged
+      env:
+        GH_TOKEN: ${{ github.token }}
+        GH_EVENT: ${{ github.event_name }}
+      run: |
+        case "$GH_EVENT" in
+          push)
+            echo "mergedSha=${{ github.sha }}" >> "$GITHUB_OUTPUT"
+            ;;
+          pull_request_target)
+            if mergedSha=$(base/ci/get-merge-commit.sh ${{ github.repository }} ${{ github.event.number }}); then
+              echo "Checking the merge commit $mergedSha"
+              echo "mergedSha=$mergedSha" >> "$GITHUB_OUTPUT"
+            else
+              # Skipping so that no notifications are sent
+              echo "Skipping the rest..."
+            fi
+            ;;
+        esac
+        rm -rf base

.github/workflows/nixpkgs-vet.yml

@@ -19,46 +19,34 @@ permissions: {}
 # There is a feature request for suppressing notifications on concurrency-canceled runs: https://github.com/orgs/community/discussions/13015
 
 jobs:
+  get-merge-commit:
+    uses: ./.github/workflows/get-merge-commit.yml
+
   check:
     name: nixpkgs-vet
     # This needs to be x86_64-linux, because we depend on the tooling being pre-built in the GitHub releases.
     runs-on: ubuntu-latest
     # This should take 1 minute at most, but let's be generous. The default of 6 hours is definitely too long.
     timeout-minutes: 10
+    needs: get-merge-commit
     steps:
-      # This checks out the base branch because of pull_request_target
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          path: base
-          sparse-checkout: ci
-      - name: Resolving the merge commit
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          if mergedSha=$(base/ci/get-merge-commit.sh ${{ github.repository }} ${{ github.event.number }}); then
-            echo "Checking the merge commit $mergedSha"
-            echo "mergedSha=$mergedSha" >> "$GITHUB_ENV"
-          else
-            echo "Skipping the rest..."
-          fi
-          rm -rf base
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        if: env.mergedSha
+        if: needs.get-merge-commit.outputs.mergedSha
         with:
           # pull_request_target checks out the base branch by default
-          ref: ${{ env.mergedSha }}
+          ref: ${{ needs.get-merge-commit.outputs.mergedSha }}
           # Fetches the merge commit and its parents
           fetch-depth: 2
       - name: Checking out base branch
-        if: env.mergedSha
+        if: needs.get-merge-commit.outputs.mergedSha
         run: |
           base=$(mktemp -d)
           git worktree add "$base" "$(git rev-parse HEAD^1)"
           echo "base=$base" >> "$GITHUB_ENV"
       - uses: cachix/install-nix-action@08dcb3a5e62fa31e2da3d490afc4176ef55ecd72 # v30
-        if: env.mergedSha
+        if: needs.get-merge-commit.outputs.mergedSha
       - name: Fetching the pinned tool
-        if: env.mergedSha
+        if: needs.get-merge-commit.outputs.mergedSha
         # Update the pinned version using ci/nixpkgs-vet/update-pinned-tool.sh
         run: |
           # The pinned version of the tooling to use.
@@ -71,7 +59,7 @@ jobs:
           # Adds a result symlink as a GC root.
           nix-store --realise "$toolPath" --add-root result
       - name: Running nixpkgs-vet
-        if: env.mergedSha
+        if: needs.get-merge-commit.outputs.mergedSha
         env:
           # Force terminal colors to be enabled. The library that `nixpkgs-vet` uses respects https://bixense.com/clicolors/
           CLICOLOR_FORCE: 1

ci/README.md

@@ -58,7 +58,7 @@ Exit codes:
 
 ### Usage
 
-This script can be used in GitHub Actions workflows as follows:
+This script is implemented as a reusable GitHub Actions workflow, and can be used as follows:
 
 ```yaml
 on: pull_request_target
@@ -67,32 +67,19 @@ on: pull_request_target
 permissions: {}
 
 jobs:
+  get-merge-commit:
+    # use the relative path of the get-merge-commit workflow yaml here
+    uses: ./.github/workflows/get-merge-commit.yml
+
   build:
     name: Build
     runs-on: ubuntu-latest
+    needs: get-merge-commit
     steps:
-      # Important: Because of `pull_request_target`, this doesn't check out the PR,
-      # but rather the base branch of the PR, which is needed so we don't run untrusted code
-      - uses: actions/checkout@<VERSION>
-        with:
-          path: base
-          sparse-checkout: ci
-      - name: Resolving the merge commit
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          if mergedSha=$(base/ci/get-merge-commit.sh ${{ github.repository }} ${{ github.event.number }}); then
-            echo "Checking the merge commit $mergedSha"
-            echo "mergedSha=$mergedSha" >> "$GITHUB_ENV"
-          else
-            # Skipping so that no notifications are sent
-            echo "Skipping the rest..."
-          fi
-          rm -rf base
       - uses: actions/checkout@<VERSION>
         # Add this to _all_ subsequent steps to skip them
-        if: env.mergedSha
+        if: needs.get-merge-commit.outputs.mergedSha
         with:
-          ref: ${{ env.mergedSha }}
+          ref: ${{ needs.get-merge-commit.outputs.mergedSha }}
       - ...
 ```

doc/build-helpers/fetchers.chapter.md

@@ -755,6 +755,9 @@ Used with Subversion. Expects `url` to a Subversion directory, `rev`, and `hash`
 
 Used with Git. Expects `url` to a Git repo, `rev`, and `hash`. `rev` in this case can be full the git commit id (SHA1 hash) or a tag name like `refs/tags/v1.0`.
 
+If you want to fetch a tag you should pass the `tag` parameter instead of `rev` which has the same effect as setting `rev = "refs/tags"/${version}"`.
+This is safer than just setting `rev = version` w.r.t. possible branch and tag name conflicts.
+
 Additionally, the following optional arguments can be given:
 
 *`fetchSubmodules`* (Boolean)
@@ -833,7 +836,7 @@ A number of fetcher functions wrap part of `fetchurl` and `fetchzip`. They are m
 
 ## `fetchFromGitHub` {#fetchfromgithub}
 
-`fetchFromGitHub` expects four arguments. `owner` is a string corresponding to the GitHub user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every GitHub HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `hash` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available, but `hash` is currently preferred.
+`fetchFromGitHub` expects four arguments. `owner` is a string corresponding to the GitHub user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every GitHub HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. If you need to fetch a tag however, you should prefer to use the `tag` parameter which achieves this in a safer way with less boilerplate. Finally, `hash` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available, but `hash` is currently preferred.
 
 To use a different GitHub instance, use `githubBase` (defaults to `"github.com"`).
 

doc/build-helpers/testers.chapter.md

@@ -364,7 +364,7 @@ including `nativeBuildInputs` to specify dependencies available to the `script`.
 ```nix
 testers.runCommand {
   name = "access-the-internet";
-  command = ''
+  script = ''
     curl -o /dev/null https://example.com
     touch $out
   '';