Merge branch 'master' into eslint-plugin-refactor

community/approved-plugins.json

@@ -454,6 +454,11 @@
     "description": "Nx plugin to support Firebase Apps and Cloud Functions in Nx workspaces",
     "url": "https://github.com/simondotm/nx-firebase"
   },
+  {
+    "name": "@dman926/nx-python-pdm",
+    "description": "Use Python in NX workspaces with PDM",
+    "url": "https://github.com/dman926/nx-python-pdm"
+  },
   {
     "name": "@gnuechtel/nx-cucumber",
     "description": "Plugin to use Cucumber within Nx workspaces",

docs/shared/monorepo-ci-azure.md

@@ -24,10 +24,12 @@ jobs:
     pool:
       vmImage: 'ubuntu-latest'
     steps:
+      - checkout: self
+        fetchDepth: 0
+
       # Set Azure Devops CLI default settings
       - bash: az devops configure --defaults organization=$(System.TeamFoundationCollectionUri) project=$(System.TeamProject)
         displayName: 'Set default Azure DevOps organization and project'
-
       # Get last successfull commit from Azure Devops CLI
       - displayName: 'Get last successful commit SHA'
         condition: ne(variables['Build.Reason'], 'PullRequest')
@@ -45,39 +47,19 @@ jobs:
 
       # Required for nx affected if we're on a branch
       - script: git branch --track main origin/main
-      - script: npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="build" # this line enables distribution
+      # This line enables distribution
+      # The "--stop-agents-after" is optional, but allows idle agents to shut down once the "e2e-ci" targets have been requested
+      - script: npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="e2e-ci"
       - script: npm ci
+
       - script: npx nx-cloud record -- nx format:check --base=$(BASE_SHA)
-      - script: npx nx affected --base=$(BASE_SHA) -t lint test build --parallel=3
+      - script: npx nx affected --base=$(BASE_SHA) -t lint test build e2e-ci
 ```
 
-{% callout type="note" title="Check your Shallow Fetch settings" %}
-
-Nx needs additional Git history available for [`affected`](/ci/features/affected) to function correctly. Make sure
-Shallow fetching is disabled in your pipeline settings UI. For more info, check out this article from
-Microsoft [here](https://learn.microsoft.com/en-us/azure/devops/pipelines/yaml-schema/steps-checkout?view=azure-pipelines#shallow-fetch).
-
-{% /callout %}
-
-Unlike `GitHub Actions` and `CircleCI`, you don't have the metadata to help you track the last successful run on `main`.
-In the example below, the base is set to `HEAD~1` (for push) or branching point (for pull requests), but a more robust
-solution would be to tag a SHA in the main job once it succeeds and then use this tag as a base. You can also
-try [using the devops CLI within the pipeline yaml](#get-the-commit-of-the-last-successful-build). See
-the [nx-tag-successful-ci-run](https://github.com/nrwl/nx-tag-successful-ci-run)
-and [nx-set-shas](https://github.com/nrwl/nx-set-shas) (version 1 implements tagging mechanism) repositories for more
-information.
-
-We also have to set `NX_BRANCH` explicitly. NX_BRANCH does not impact the functionality of your runs, but does provide a
-human-readable label to easily identify them in the Nx Cloud app.
-
-The `main` job implements the CI workflow.
-
 ## Get the Commit of the Last Successful Build
 
-In the example above we ran a script to retrieve the commit of the last successful build. The idea is to
-use [Azure Devops CLI](https://learn.microsoft.com/en-us/cli/azure/pipelines?view=azure-cli-latest)
-directly in
-the [Pipeline Yaml](https://learn.microsoft.com/en-us/azure/devops/cli/azure-devops-cli-in-yaml?view=azure-devops)
+In the example above, we ran a script to retrieve the commit of the last successful build. The idea is to
+use [Azure Devops CLI](https://learn.microsoft.com/en-us/cli/azure/pipelines?view=azure-cli-latest) directly in the [Pipeline Yaml](https://learn.microsoft.com/en-us/azure/devops/cli/azure-devops-cli-in-yaml?view=azure-devops)
 
 First, we configure Devops CLI
 
@@ -100,17 +82,15 @@ Then we can query the pipelines API (providing the auth token)
     AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)
 ```
 
-We can target a specific build, in this example we specified:
+We can target a specific build; in this example, we specified:
 
 - The branch (--branch)
-- The pipeline Id (--definition-ids)
+- The pipeline ID (--definition-ids)
 - The result type (--result)
-- The number of result (-top)
+- The number of the result (-top)
 
-By default the command returns an entire JSON object with all the information. But we can narrow it down to the desired
-result with the `--query` param that uses [JMESPath](https://jmespath.org/)
+The command returns an entire JSON object with all the information. But we can narrow it down to the desired result with the `--query` param that uses [JMESPath](https://jmespath.org/)
 format ([more details](https://learn.microsoft.com/en-us/cli/azure/query-azure-cli?tabs=concepts%2Cbash))
 
-Finally we extract the result in a
-common [custom variable](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/set-variables-scripts?view=azure-devops&tabs=bash)
-named `BASE_SHA` used later by `nx affected` commands
+Finally, we extract the result in a common [custom variable](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/set-variables-scripts?view=azure-devops&tabs=bash)
+named `BASE_SHA` used later by the `nx format` and `nx affected` commands.

docs/shared/monorepo-ci-bitbucket-pipelines.md

@@ -1,33 +1,46 @@
 # Configuring CI Using Bitbucket Pipelines and Nx
 
-Below is an example of an Bitbucket Pipelines, building and testing only what is affected.
+Below is an example of a Bitbucket Pipelines, building and testing only what is affected.
 
 ```yaml {% fileName="bitbucket-pipelines.yml" %}
 image: node:20
+
+clone:
+  depth: full
+
 pipelines:
   pull-requests:
     '**':
       - step:
           name: 'Build and test affected apps on Pull Requests'
-          caches: # optional
-            - node
           script:
-            - npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="build" # this line enables distribution
+            # This line enables distribution
+            # The "--stop-agents-after" is optional, but allows idle agents to shut down once the "e2e-ci" targets have been requested
+            - npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="e2e-ci"
             - npm ci
+
             - npx nx-cloud record -- nx format:check
-            - npx nx affected -t lint test build --base=origin/master --head=HEAD
+            - npx nx affected -t lint test build e2e-ci --base=origin/main
 
   branches:
     main:
       - step:
           name: "Build and test affected apps on 'main' branch changes"
-          caches: # optional
-            - node
           script:
-            - npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="build" # this line enables distribution
+            - export NX_BRANCH=$BITBUCKET_PR_ID
+            # This line enables distribution
+            # The "--stop-agents-after" is optional, but allows idle agents to shut down once the "e2e-ci" targets have been requested
+            - npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="e2e-ci"
             - npm ci
+
             - npx nx-cloud record -- nx format:check
-            - npx nx affected -t lint test build --base=HEAD~1
+            - npx nx affected -t lint test build e2e-ci --base=HEAD~1
 ```
 
 The `pull-requests` and `main` jobs implement the CI workflow.
+
+### Get the Commit of the Last Successful Build
+
+Unlike `GitHub Actions` and `CircleCI`, you don't have the metadata to help you track the last successful run on `main`. In the example below, the base is set to `HEAD~1` (for push) or branching point (for pull requests), but a more robust solution would be to tag an SHA in the main job once it succeeds and then use this tag as a base. See the [nx-tag-successful-ci-run](https://github.com/nrwl/nx-tag-successful-ci-run) and [nx-set-shas](https://github.com/nrwl/nx-set-shas) (version 1 implements tagging mechanism) repositories for more information.
+
+We also have to set `NX_BRANCH` explicitly.

docs/shared/monorepo-ci-circle-ci.md

@@ -1,23 +1,28 @@
 # Configuring CI Using Circle CI and Nx
 
-Below is an example of an Circle CI setup, building and testing only what is affected.
+Below is an example of a Circle CI setup, building, and testing only what is affected.
 
 ```yaml {% fileName=".circleci/config.yml" %}
 version: 2.1
+
 orbs:
-  nx: nrwl/[email protected]
+  nx: nrwl/[email protected]
+
 jobs:
   main:
     docker:
       - image: cimg/node:lts-browsers
     steps:
       - checkout
-      - run: npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="build" # this line enables distribution
+      # This line enables distribution
+      # The "--stop-agents-after" is optional, but allows idle agents to shut down once the "e2e-ci" targets have been requested
+      - run: npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="e2e-ci"
       - run: npm ci
+
       - nx/set-shas
 
       - run: npx nx-cloud record -- nx format:check
-      - run: npx nx affected --base=$NX_BASE --head=$NX_HEAD -t lint test build --parallel=3
+      - run: npx nx affected --base=$NX_BASE --head=$NX_HEAD -t lint test build e2e-ci
 workflows:
   build:
     jobs:
@@ -26,13 +31,13 @@ workflows:
 
 ### Get the Commit of the Last Successful Build
 
-`CircleCI` can track the last successful run on the `main` branch and use this as a reference point for the `BASE`. The `Nx Orb` provides a convenient implementation of this functionality which you can drop into your existing CI config. Specifically, `nx/set-shas` populates the `$NX_BASE` environment variable with the commit SHA of the last successful run.
+`CircleCI` can track the last successful run on the `main` branch and use this as a reference point for the `BASE`. The [Nx Orb](https://github.com/nrwl/nx-orb) provides a convenient implementation of this functionality, which you can drop into your existing CI workflow. Specifically, for push commits, `nx/set-shas` populates the `$NX_BASE` environment variable with the commit SHA of the last successful run.
 
 To understand why knowing the last successful build is important for the affected command, check out the [in-depth explanation in Orb's docs](https://github.com/nrwl/nx-orb#background).
 
 ### Using CircleCI in a private repository
 
-To use the [Nx Orb](https://github.com/nrwl/nx-orb) with a private repository on your main branch, you need to grant the orb access to your CircleCI API. You can do this by creating an environment variable called `CIRCLE_API_TOKEN` in the context or the project.
+To use the [Nx Orb](https://github.com/nrwl/nx-orb) with a private repository on your main branch, you need to grant the orb access to your CircleCI API. Create an environment variable called `CIRCLE_API_TOKEN` in the context of the project.
 
 {% callout type="warning" title="Caution" %}
 It should be a user token, not the project token.

docs/shared/monorepo-ci-github-actions.md

@@ -1,6 +1,6 @@
 # Configuring CI Using GitHub Actions and Nx
 
-Below is an example of an GitHub Actions setup, building and testing only what is affected.
+Below is an example of a GitHub Actions setup, building, and testing only what is affected.
 
 ```yaml {% fileName=".github/workflows/ci.yml" %}
 name: CI
@@ -23,22 +23,25 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      # Cache node_modules
       - uses: actions/setup-node@v3
         with:
           node-version: 20
           cache: 'npm'
-      - run: npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="build" # this line enables distribution
+      # This line enables distribution
+      # The "--stop-agents-after" is optional, but allows idle agents to shut down once the "e2e-ci" targets have been requested
+      - run: npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="e2e-ci"
       - run: npm ci
+
       - uses: nrwl/nx-set-shas@v3
       # This line is needed for nx affected to work when CI is running on a PR
       - run: git branch --track main origin/main
 
       - run: npx nx-cloud record -- nx format:check
-      - run: npx nx affected -t lint test build --parallel=3
+      - run: npx nx affected -t lint test build e2e-ci
 ```
 
 ### Get the Commit of the Last Successful Build
 
-`GitHub` can track the last successful run on the `main` branch and use this as a reference point for the `BASE`. The `nrwl/nx-set-shas` provides a convenient implementation of this functionality which you can drop into your existing CI config.
+The `GitHub` can track the last successful run on the `main` branch and use this as a reference point for the `BASE`. The [nrwl/nx-set-shas](https://github.com/marketplace/actions/nx-set-shas) provides a convenient implementation of this functionality, which you can drop into your existing CI workflow.
+
 To understand why knowing the last successful build is important for the affected command, check out the [in-depth explanation in Actions's docs](https://github.com/marketplace/actions/nx-set-shas#background).

docs/shared/monorepo-ci-gitlab.md

@@ -1,16 +1,14 @@
 # Configuring CI Using GitLab and Nx
 
-Below is an example of an GitLab setup, building and testing only what is affected.
+Below is an example of a GitLab setup, building and testing only what is affected.
 
 ```yaml {% fileName=".gitlab-ci.yml" %}
-image: node:18
+image: node:20
 
-stages:
-  - lint
-  - test
-  - build
+variables:
+  GIT_DEPTH: 0
 
-.distributed:
+main:
   interruptible: true
   only:
     - main
@@ -21,36 +19,15 @@ stages:
         - package-lock.json
     paths:
       - .npm/
-  before_script:
-    - npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="build" # this line enables distribution
+  script:
+    # Connect your workspace on <%= nxCloudHost %> and uncomment this to enable task distribution.
+    # The "--stop-agents-after" is optional, but allows idle agents to shut down once the "e2e-ci" targets have been requested
+    - npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js" --stop-agents-after="e2e-ci"
+
     - npm ci --cache .npm --prefer-offline
     - NX_HEAD=$CI_COMMIT_SHA
     - NX_BASE=${CI_MERGE_REQUEST_DIFF_BASE_SHA:-$CI_COMMIT_BEFORE_SHA}
 
-variables:
-  GIT_DEPTH: 0
-
-format-check:
-  stage: test
-  extends: .distributed
-  script:
     - npx nx-cloud record -- nx format:check --base=$NX_BASE --head=$NX_HEAD
-
-lint:
-  stage: test
-  extends: .distributed
-  script:
-    - npx nx affected --base=$NX_BASE --head=$NX_HEAD -t lint --parallel=3
-
-test:
-  stage: test
-  extends: .distributed
-  script:
-    - npx nx affected --base=$NX_BASE --head=$NX_HEAD -t test --parallel=3
-
-build:
-  stage: build
-  extends: .distributed
-  script:
-    - npx nx affected --base=$NX_BASE --head=$NX_HEAD -t build --parallel=3
+    - npx nx affected --base=$NX_BASE --head=$NX_HEAD -t lint test build e2e-ci
 ```

docs/shared/monorepo-ci-jenkins.md

@@ -1,6 +1,6 @@
 # Configuring CI Using Jenkins and Nx
 
-Below is an example of an Jenkins setup, building and testing only what is affected.
+Below is an example of a Jenkins setup, building and testing only what is affected.
 
 ```groovy
 pipeline {
@@ -17,10 +17,12 @@ pipeline {
                     }
                     agent any
                     steps {
-                        sh "npx nx-cloud start-ci-run --distribute-on='5 linux-medium-js' --stop-agents-after='build'" // this line enables distribution
+                        // This line enables distribution
+                        // The "--stop-agents-after" is optional, but allows idle agents to shut down once the "e2e-ci" targets have been requested
+                        sh "npx nx-cloud start-ci-run --distribute-on='5 linux-medium-js' --stop-agents-after='e2e-ci'"
                         sh "npm ci"
                         sh "npx nx-cloud record -- nx format:check"
-                        sh "npx nx affected --base=HEAD~1 -t lint test build --parallel=3"
+                        sh "npx nx affected --base=HEAD~1 -t lint test build e2e-ci"
                     }
                 }
                 stage('PR') {
@@ -29,10 +31,12 @@ pipeline {
                     }
                     agent any
                     steps {
-                        sh "npx nx-cloud start-ci-run --distribute-on='5 linux-medium-js' --stop-agents-after='build'" // this line enables distribution
+                        // This line enables distribution
+                        // The "--stop-agents-after" is optional, but allows idle agents to shut down once the "e2e-ci" targets have been requested
+                        sh "npx nx-cloud start-ci-run --distribute-on='5 linux-medium-js' --stop-agents-after='e2e-ci'"
                         sh "npm ci"
                         sh "npx nx-cloud record -- nx format:check"
-                        sh "npx nx affected --base origin/${env.CHANGE_TARGET} -t lint test build --parallel=3"
+                        sh "npx nx affected --base origin/${env.CHANGE_TARGET} -t lint test build e2e-ci"
                     }
                 }
             }