Skip to content

Commit d68e6e9

Browse files
committed
Fix/clarify docs about cloud builds
1 parent 0bfe143 commit d68e6e9

File tree

1 file changed

+16
-5
lines changed

1 file changed

+16
-5
lines changed

doc/cloudbuild.md

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -76,14 +76,14 @@ This means you can use these variables in subsequent steps in your cloud build
7676
such as publishing artifacts, so that your richer version information can be
7777
expressed in the publish location or artifact name.
7878

79-
Enable this feature by setting the `cloudBuild.setVersionVariables` field
80-
in your `version.json` file to `true`, as shown below:
79+
This feature is enabled by default via the `cloudBuild.setVersionVariables` field
80+
in your `version.json` file, which defaults as shown below:
8181

8282
```json
8383
{
8484
"version": "1.0",
8585
"cloudBuild": {
86-
"setVersionVariables": true
86+
"setVersionVariables": true // the default value
8787
}
8888
}
8989
```
@@ -106,7 +106,18 @@ Setting both of these fields to `true` means that a few variables will be define
106106

107107
While each individual MSBuild project has its own version computed, the versions across projects are usually the same so long as you have one `version.json` file at the root of your repo. If you choose to enable setting of cloud build variables in that root version.json file, each project that builds will take a turn setting those cloud build variables. This is perhaps more work than is necessary, and when some projects compute versions differently it can lead to inconsistently defined cloud build variables, based on non-deterministic build ordering of your projects.
108108

109-
You can reduce log message noise and control for non-deterministic cloud build variables by *not* setting any of the `cloudBuild` options in your root version.json file. Two options are described below to set the cloud build number and variables just once in your build.
109+
You can reduce log message noise and control for non-deterministic cloud build variables by disabling all the settings under the `cloudBuild` options in your root version.json file (including disabling default behavior):
110+
111+
```js
112+
{
113+
"version": "1.0",
114+
"cloudBuild": {
115+
"setVersionVariables": false // override the default value of true
116+
}
117+
}
118+
```
119+
120+
Two options are described below to set the cloud build number and variables just once in your build.
110121

111122
#### Set the cloud build number as a build step
112123

@@ -117,7 +128,7 @@ dotnet tool install --tool-path . nbgv
117128
.\nbgv cloud
118129
```
119130

120-
The above will set just the cloud build number, but switches to the `nbgv cloud` command will cause other build variables to also be set.
131+
The above will set just the cloud build number, but switches you can add to the `nbgv cloud` command will cause other build variables to also be set.
121132

122133
See a working sample in [a VSTS YAML file](https://github.com/Humanizr/Humanizer/blob/11bd9fd99c151f2e84eb9d4fa082a6c077504c9f/azure-pipelines.yml#L21-L29).
123134

0 commit comments

Comments
 (0)