You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/cloudbuild.md
+53-1Lines changed: 53 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,7 +14,7 @@ in MSBuild, gulp and other build scripts.
14
14
## Optional features
15
15
16
16
By specifying certain `cloudBuild` options in your `version.json` file,
17
-
you can activate features for some cloud build systems, as follows
17
+
you can activate features for some cloud build systems, as follows:
18
18
19
19
### Automatically match cloud build numbers to to your git version
20
20
@@ -77,6 +77,58 @@ in your `version.json` file to `true`, as shown below:
77
77
}
78
78
```
79
79
80
+
There are many more MSBuild variables that the build will set within the build. To make *all* these available as cloud variables (prefixed with `NBGV_`), you can set the `cloudBuild.setAllVariables` field to `true`:
81
+
82
+
```json
83
+
{
84
+
"version": "1.0",
85
+
"cloudBuild": {
86
+
"setVersionVariables": true,
87
+
"setAllVariables": true
88
+
}
89
+
}
90
+
```
91
+
92
+
Setting both of these fields to `true` means that a few variables will be defined in the cloud build server twice -- one set with the names in the table above and the other (full) set using the `NBGV_` prefix.
93
+
94
+
### Set cloud build variables only once in a build
95
+
96
+
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.
97
+
98
+
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.
99
+
100
+
#### Set the cloud build number as a build step
101
+
102
+
The [nbgv CLI tool](nbgv-cli.md) can be used to set the cloud build number and variables. Your CI build script should include these two commands:
103
+
104
+
```cmd
105
+
dotnet tool install --tool-path . nbgv
106
+
.\nbgv cloud
107
+
```
108
+
109
+
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.
110
+
111
+
See a working sample in [a VSTS YAML file](https://github.com/Humanizr/Humanizer/blob/604ebcc5ed0215aa8fb511ac5424239659f570a0/.vsts-shared.yml#L5-L15).
After ensuring that your root version.json file does *not* set `cloudBuild.buildNumber.enabled=true`, define an additional `version.json` file inside just *one* project directory that inherits from the base one, like this:
## Dealing with legacy version.txt or version.json files
4
+
5
+
When you already have a version.txt or version.json file in your repo and want to use Nerdbank.GitVersioning,
6
+
you may find that your build breaks when NB.GV tries to parse your version.txt or version.json file(s).
7
+
8
+
Any such version.txt or version.json files in project directories with NB.GV installed, or any parent directory up to the repo root, must be removed in a commit *prior* to the commit that defines the new NB.GV-compliant version.json file. This will ensure that NB.GV will not discover the legacy files and try to parse them.
9
+
10
+
It is important that you maintain that clean break where no commit with a NB.GV version.json file has an immediate parent commit with a legacy version file. A merge commit (like a pull request with your migration changes would create) will defeat your work by having the new version.json file and an immediate parent with the version.txt file (the one from your base branch). It is therefore mandatory that if you have such a legacy file, that when you're done validating the migration that you *directly push your 2+ commits to your branch* rather than complete a pull request. If your team's policy is to use pull requests, you can create one for review, but complete it by pushing the commits directly rather than letting the git service create the merge commit for you by completing the pull request. If the push is rejected because it is not a fast-forward merge, *rebase* your changes since a local merge commit would similarly defeat your efforts.
11
+
12
+
Also note that any other open pull requests that are based on a commit from before your changes may also introduce the problematic merge commit by providing a direct parent commit path from the new version.json file to the legacy one. These open PRs must be squashed when completed or rebased.
13
+
14
+
## Maintaining an incrementing version number
15
+
16
+
When defining your new [version.json file](versionJson.md), you should set the version to be same *major.minor* version that you used before or higher.
17
+
If you are matching the prior *major.minor* version and need the build height integer (usually the 3rd integer) of your version to start higher than the last version from your legacy mechanism, set the `"buildNumberOffset"` field in the version.json file to be equal to or greater than the 3rd integer in the old version. Note that the first build height will be *one more than* the number you set here, since the commit with your changes adds to the offset you specify.
18
+
19
+
For example, suppose your last release was of version 1.2.4. When you switch to NB.GV, you may use a `version.json` file with this content:
20
+
21
+
```json
22
+
{
23
+
"version": "1.2",
24
+
"buildNumberOffset": 4
25
+
}
26
+
```
27
+
28
+
After commiting this change, the first version NB.GV will assign to your build is `1.2.5`.
29
+
30
+
When you later want to ship v1.3, remove the second field so that the 3rd integer resets:
31
+
32
+
```json
33
+
{
34
+
"version": "1.3"
35
+
}
36
+
```
37
+
38
+
This will make your first 1.3 build be versioned as 1.3.1.
Perform a one-time install of the `nbgv` tool using the following dotnet CLI command:
4
+
5
+
```ps1
6
+
dotnet tool install -g nbgv
7
+
```
8
+
9
+
You may then use the `nbgv` tool to install Nerdbank.GitVersioning into your repos, as well as query and update version information for your repos and projects.
10
+
11
+
Install Nerdbank.GitVersioning into your repo using this command from within your repo:
12
+
13
+
```ps1
14
+
nbgv install
15
+
```
16
+
17
+
This will create your initial `version.json` file.
18
+
It will also add/modify your `Directory.Build.props` file in the root of your repo to add the `PackageReference` to the latest `Nerdbank.GitVersioning` package available on nuget.org.
19
+
20
+
## CI Builds
21
+
22
+
If scripting for running in a CI build where global impact from installing a tool is undesirable, you can localize the tool installation:
23
+
24
+
```ps1
25
+
dotnet tool install --tool-path . nbgv
26
+
```
27
+
28
+
At this point you can launch the tool using `.\nbgv` in your build script.
29
+
30
+
## Learn more
31
+
32
+
There are several more sub-commands and switches to each to help you build and maintain your projects, find a commit that built a particular version later on, create tags, etc.
33
+
34
+
Use the `--help` switch on the `nbgv` command or one of its sub-commands to learn about the sub-commands available and how to use them. For example, this is the basic usage help text:
35
+
36
+
```cmd
37
+
nbgv --help
38
+
usage: nbgv <command> [<args>]
39
+
40
+
install Prepares a project to have version stamps applied
41
+
using Nerdbank.GitVersioning.
42
+
get-version Gets the version information for a project.
43
+
set-version Updates the version stamp that is applied to a
44
+
project.
45
+
tag Creates a git tag to mark a version.
46
+
get-commits Gets the commit(s) that match a given version.
47
+
cloud Communicates with the ambient cloud build to set the
You must also create [a version.json file](doc/versionJson.md) in your repo.
32
+
You must also create [a version.json file](doc/versionJson.md) in your repo. See [migration notes](doc/migrating.md) if your repo already has a version.txt or version.json file from using another system.
32
33
33
34
## How to leverage version stamping and runtime information
34
35
@@ -59,7 +60,7 @@ the git 'height' of the version, and the git commit ID.
59
60
### Version generation
60
61
61
62
Given the same settings as used in the discussion above, a NuGet or NPM package may be
62
-
assigned this version:
63
+
assigned this version:
63
64
64
65
1.0.24-alpha-g9a7eb6c819
65
66
@@ -86,7 +87,7 @@ The git commit ID does not represent an alphanumerically sortable identifier
86
87
in semver, and thus delivers a poor package update experience for NuGet package
87
88
consumers. Incrementing the PATCH with each public release ensures that users
88
89
who want to update to your latest NuGet package will reliably get the latest
89
-
version.
90
+
version.
90
91
91
92
The git height is guaranteed to always increase with each release within a given major.minor version,
92
93
assuming that each release builds on a previous release. And the height automatically resets when
@@ -98,14 +99,14 @@ It could be, but the git height serves as a pseudo-identifier already and the
98
99
git commit id would just make it harder for users to type in the version
99
100
number if they ever had to.
100
101
101
-
Note that the git commit ID is *always* included in the
102
+
Note that the git commit ID is *always* included in the
102
103
`AssemblyInformationVersionAttribute` so one can always match a binary to the
103
104
exact version of source code that produced it.
104
105
105
106
### How do I translate from a version to a git commit and vice versa?
106
107
107
108
A pair of Powershell scripts are included in the Nerdbank.GitVersioning NuGet package
108
-
that can help you to translate between the two representations.
109
+
that can help you to translate between the two representations.
0 commit comments