miel.truyen/nx
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity

docs(core): add more realistic graph example and some other improvements

Browse Source
This commit is contained in:
Juri 2023-11-29 13:40:46 +01:00 committed by Juri Strumpflohner
parent 434dee2417
commit 1f4346f44e
1 changed files with 156 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

217
docs/shared/using-nx/affected.md
View File

@ -10,11 +10,9 @@ When you run `nx affected -t test`, Nx uses Git to determine the files you chang
change (what exactly did you update in those files), and it uses this to determine the list of projects in the workspace change (what exactly did you update in those files), and it uses this to determine the list of projects in the workspace
that can be affected by this change. It then runs the `run-many` command with that list. that can be affected by this change. It then runs the `run-many` command with that list.
For instance, if my PR changes `lib`, and I then run `nx affected -t test`, Nx figures out that `app1` and `app2` For instance, if my PR changes `lib10`, and we then run `nx affected -t test`, Nx leverages the project graph to determine all the projects that depend on `lib10`, marks them as "affected" and runs `test` on just that subset of projects.
depend on `lib`, so it will invoke `nx run-many -t test -p app1 app2 lib`.
{% side-by-side %} {% graph title="Making a change in lib10 only affects a sub-part of the project graph" height="400px" %}
{% graph title="Changing app1 can only affect app1" height="250px" %}
```json ```json
{ {
@ -31,56 +29,62 @@ depend on `lib`, so it will invoke `nx run-many -t test -p app1 app2 lib`.
}, },
{ {
"type": "lib", "type": "lib",
"name": "lib", "name": "lib1",
"data": {}
}
],
"groupByFolder": false,
"workspaceLayout": {
"appsDir": "apps",
"libsDir": "libs"
},
"dependencies": {
"app1": [
{
"target": "lib",
"source": "app1",
"type": "direct"
}
],
"app2": [
{
"target": "lib",
"source": "app2",
"type": "direct"
}
],
"lib": []
},
"affectedProjectIds": ["app1"]
}
```
{% /graph %}
{% graph title="Changing lib can affect lib, app1 and app2" height="250px" %}
```json
{
"projects": [
{
"type": "app",
"name": "app1",
"data": {}
},
{
"type": "app",
"name": "app2",
"data": {} "data": {}
}, },
{ {
"type": "lib", "type": "lib",
"name": "lib", "name": "lib2",
"data": {}
},
{
"type": "lib",
"name": "lib3",
"data": {}
},
{
"type": "lib",
"name": "lib4",
"data": {}
},
{
"type": "lib",
"name": "lib5",
"data": {}
},
{
"type": "lib",
"name": "lib6",
"data": {}
},
{
"type": "lib",
"name": "lib7",
"data": {}
},
{
"type": "lib",
"name": "lib8",
"data": {}
},
{
"type": "lib",
"name": "lib9",
"data": {}
},
{
"type": "lib",
"name": "lib10",
"data": {}
},
{
"type": "lib",
"name": "lib11",
"data": {}
},
{
"type": "lib",
"name": "lib12",
"data": {} "data": {}
} }
], ],
@ -92,33 +96,116 @@ depend on `lib`, so it will invoke `nx run-many -t test -p app1 app2 lib`.
"dependencies": { "dependencies": {
"app1": [ "app1": [
{ {
"target": "lib", "target": "lib1",
"source": "app1",
"type": "direct"
},
{
"target": "lib2",
"source": "app1", "source": "app1",
"type": "direct" "type": "direct"
} }
], ],
"app2": [ "app2": [
{ {
"target": "lib", "target": "lib4",
"source": "app2",
"type": "direct"
},
{
"target": "lib5",
"source": "app2",
"type": "direct"
},
{
"target": "lib6",
"source": "app2", "source": "app2",
"type": "direct" "type": "direct"
} }
], ],
"lib": [] "lib1": [
{
"target": "lib7",
"source": "lib1",
"type": "direct"
},
{
"target": "lib8",
"source": "lib1",
"type": "direct"
}
],
"lib2": [
{
"target": "lib3",
"source": "lib2",
"type": "direct"
}
],
"lib3": [
{
"target": "lib8",
"source": "lib3",
"type": "direct"
}
],
"lib4": [
{
"target": "lib3",
"source": "lib4",
"type": "direct"
},
{
"target": "lib9",
"source": "lib4",
"type": "direct"
},
{
"target": "lib10",
"source": "lib4",
"type": "direct"
}
],
"lib5": [
{
"target": "lib10",
"source": "lib5",
"type": "direct"
},
{
"target": "lib11",
"source": "lib5",
"type": "direct"
},
{
"target": "lib12",
"source": "lib5",
"type": "direct"
}
],
"lib6": [
{
"target": "lib12",
"source": "lib6",
"type": "direct"
}
],
"lib7": [],
"lib8": [],
"lib9": [],
"lib10": [],
"lib11": [],
"lib12": []
}, },
"affectedProjectIds": ["app1", "app2", "lib"] "affectedProjectIds": ["lib10", "lib4", "lib5", "app2"]
} }
``` ```
{% /graph %} {% /graph %}
{% /side-by-side %}
Nx analyzes the nature of the changes. For example, if you change the version of Next.js in the package.json, Nx knows
that `app2` cannot be affected by it, so it only retests `app1`.
## Visualize Affected Projects ## Visualize Affected Projects
To visualize what is affected, run: You can also visualize the affected projects using the [Nx graph](/core-features/explore-graph). Simply run:
```shell ```shell
nx affected:graph nx affected:graph
@ -126,7 +213,9 @@ nx affected:graph
## Specify Which SHAs to Use to Calculate Affected Code ## Specify Which SHAs to Use to Calculate Affected Code
The SHAs you pass must be defined in the git repository. The `main` and `HEAD` SHAs are what you normally use while developing. Most likely you will want to provision other SHAs in your CI environment. To understand which projects are affected, Nx uses the Git history and the [project graph](/core-features/explore-graph). Git knows which files changed, and the Nx project graph knows which projects those files belong to.
The affected command takes a `base` and `head` commit. The default `base` is your `main` branch and the default `head` is your current file system. This is generally what you want when developing locally, but in CI, you need to customize these values.
```shell ```shell
nx affected:build --base=origin/main --head=$PR_BRANCH_NAME # where PR_BRANCH_NAME is defined by your CI system nx affected:build --base=origin/main --head=$PR_BRANCH_NAME # where PR_BRANCH_NAME is defined by your CI system
@ -140,7 +229,13 @@ NX_BASE=origin/main~1
NX_HEAD=origin/main NX_HEAD=origin/main
``` ```
Typically, you want to set the base SHA not the the most recent commit on the `main` branch, but rather that latest commit that successfully passed in CI. In other words, in order to be certain that the repo is in a good state, we need to check all the changes that have happened since the last time the repo was in a good state. See the setup guide for your CI provider to learn how to calculate the last successful commit. Typically, you want to set the base SHA not the most recent commit on the `main` branch, but rather that latest commit that successfully passed in CI. In other words, in order to be certain that the repo is in a good state, we need to check all the changes that have happened since the last time the repo was in a good state. Depending on your CI provider this might differ:
- [Get last successful commit for Azure Pipelines](/nx-cloud/recipes/set-up/monorepo-ci-azure#get-the-commit-of-the-last-successful-build)
- [Get last successful commit for GitHub Actions](/nx-cloud/recipes/set-up/monorepo-ci-github-actions#get-the-commit-of-the-last-successful-build)
- [Get last successful commit for CircleCI](/nx-cloud/recipes/set-up/monorepo-ci-circle-ci#get-the-commit-of-the-last-successful-build)
- [Get last successful commit for GitLab](/nx-cloud/recipes/set-up/monorepo-ci-gitlab#process-only-affected-projects-with-one-job-on-gitlab)
- [Get last successful commit for Jenkins](/nx-cloud/recipes/set-up/monorepo-ci-jenkins#get-the-commit-of-the-last-successful-build)
## Ignoring Files from Affected Commands ## Ignoring Files from Affected Commands