Merge branch 'master' into UseCsProjPackaging

Author: AArnott

.gitignore

@@ -134,6 +134,9 @@ packages
 *.nuget.targets
 project.lock.json
 
+# NPM
+package-lock.json
+
 ## TODO: If the tool you use requires repositories.config
 ## uncomment the next line
 #!packages/repositories.config

appveyor.yml

@@ -1,5 +1,16 @@
-version: 99.0.{build}
+version: '{build}'
+branches:
+  only:
+  - master
+  - /^v\d+(?:\.\d+)?$/
+  - /[\b_]validate\b/
 skip_tags: true
+skip_commits:
+  files:
+  - doc/*
+  - readme.md
+nuget:
+  disable_publish_on_pr: true
 os: Visual Studio 2017
 configuration: Release
 cache:
@@ -22,6 +33,10 @@ before_build:
 build_script:
 - ps: >-
     .\build.ps1
+test:
+  assemblies:
+    only:
+    - NerdBank.GitVersioning.Tests.dll
 artifacts:
 - path: bin\**\*.nupkg
 - path: bin\js\*.tgz

doc/cloudbuild.md

@@ -14,14 +14,14 @@ in MSBuild, gulp and other build scripts.
 ## Optional features
 
 By specifying certain `cloudBuild` options in your `version.json` file,
-you can activate features for some cloud build systems, as follows
+you can activate features for some cloud build systems, as follows:
 
 ### Automatically match cloud build numbers to to your git version
 
 Cloud builds tend to associate some calendar date or monotonically increasing
 build number to each build. These build numbers are not very informative, if at all.
 Instead, Nerdbank.GitVersioning can automatically set your cloud build's
-build number to equal the semver version calculated during your build. 
+build number to equal the semver version calculated during your build.
 
 Enable this feature by setting the `cloudBuild.buildNumber.enabled` field
 in your `version.json` file to `true`, as shown below:
@@ -59,6 +59,7 @@ range.
 | --- | --- | --- |
 | GitAssemblyInformationalVersion | AssemblyInformationalVersion | 1.3.1+g15e1898f47
 | GitBuildVersion | BuildVersion | 1.3.1.57621
+| GitBuildVersionSimple | BuildVersionSimple | 1.3.1
 
 This means you can use these variables in subsequent steps in your cloud build
 such as publishing artifacts, so that your richer version information can be
@@ -76,4 +77,45 @@ in your `version.json` file to `true`, as shown below:
 }
 ```
 
+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`:
+
+```json
+{
+  "version": "1.0",
+  "cloudBuild": {
+    "setVersionVariables": true,
+    "setAllVariables": true
+  }
+}
+```
+
+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.
+
+### Set cloud build variables from just one project
+
+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.
+
+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, and instead defining an additional `version.json` file inside just *one* project directory that inherits from the base one, like this:
+
+```json
+{
+  "inherit": true,
+  "cloudBuild": {
+    "buildNumber": {
+      "enabled": true
+    },
+    "setVersionVariables": true,
+    "setAllVariables": true
+  }
+}
+```
+
+## CI Server specific configurations
+
+### TeamCity
+TeamCity does not expose the build branch by default as an environment variable. This can be exposed by
+adding an environment variable with the value of `%teamcity.build.vcs.branch.<vcsid>%` where `<vcsid>` is
+the root id described on the TeamCity VCS roots page. Details on this variable can be found on the
+[TeamCity docs](https://confluence.jetbrains.com/display/TCD8/Predefined+Build+Parameters).
+
 [Issue37]: https://github.com/AArnott/Nerdbank.GitVersioning/issues/37

doc/dotnet-cli.md

@@ -1,8 +1,5 @@
-# DNX or dotnet CLI
+# dotnet CLI
 
-Sorry. DNX and dotnet CLI don't support extensible versioning systems. 
+The dotnet CLI works very much like [full MSBuild](msbuild.md). Just use `dotnet build` instead of `msbuild.exe`.
 
-Related issues:
-
-* [DNX#3178](https://github.com/aspnet/dnx/issues/3178)
-* [dotnet-CLI#551](https://github.com/dotnet/cli/issues/551)
+[DNX never supported extensible versioning systems](https://github.com/aspnet/dnx/issues/3178). But DNX is dead now, so you probably don't care.

doc/nuget-acquisition.md

@@ -4,15 +4,19 @@ Install the Nerdbank.GitVersioning package using the Visual Studio
 NuGet Package Manager GUI, or the NuGet Package Manager Console: 
 
 ```
-Install-Package Nerdbank-GitVersioning
+Install-Package Nerdbank.GitVersioning
 ```
 
+If in a project that uses PackageReference for this package reference, you should manually add
+`PrivateAssets="all"` to the PackageReference xml element to workaround
+[this issue](https://github.com/AArnott/Nerdbank.GitVersioning/issues/122).
+
 After installing this NuGet package, you may need to configure the version generation logic
 in order for it to work properly.
 
-With NuGet 2.x, the configuration is handled automatically via the tools\Install.ps1 script.
-For NuGet 3.x, you can run the script tools\Create-VersionFile.ps1 to help you create the
-version.json file and remove the old assembly attributes.
+When using packages.config, the configuration is handled automatically via the tools\Install.ps1 script.
+When using project.json or PackageReference, you can run the script tools\Create-VersionFile.ps1 to help
+you create the version.json file and remove the old assembly attributes.
 
 The scripts will look for the presence of a version.json or version.txt file.
 If one already exists, nothing happens. If the version file does not exist,
@@ -35,14 +39,19 @@ source code, as commonly found in your `Properties\AssemblyInfo.cs` file:
 [assembly: AssemblyInformationalVersion("1.0.0-dev")]
 ```
 
+If you are using the new VS 2017 .NET Core/Standard projects (or otherwise using the .NET SDK project type)
+you won't see these attributes in your AssemblyInfo.cs file but you may still get compiler errors
+due to duplicate attributes. In that case, a Rebuild of your project should resolve
+[the issue](https://github.com/AArnott/Nerdbank.GitVersioning/issues/121).
+
 This NuGet package creates these attributes at build time based on version information
 found in your `version.json` file and your git repo's HEAD position.
 
 When the package is installed, a version.json file is created in your project directory
-(for NuGet 2.x clients). This ensures backwards compatibility where the installation of
+(for packages.config clients). This ensures backwards compatibility where the installation of
 this package will not cause the assembly version of the project to change. If you would
 like the same version number to be applied to all projects in the repo, then you may move
-the file to the root directory of your git repo.
+the version.json file to the root directory of your git repo.
 
 Note: After first installing the package, you need to commit the version file so that
 it will be picked up during the build's version generation. If you build prior to committing,

doc/versionJson.md

@@ -14,19 +14,26 @@ Here is the content of a sample version.json file you may start with:
 The `$schema` field is optional but highly encouraged as it causes most JSON editors
 to add auto-completion and doc tips to help you author the file.
 
+Note that the capitalization of the `version.json` filename must be all lower-case
+when added to the git repo.
+
 ## File format
 
 The content of the version.json file is a JSON serialized object with these properties
 (and more):
 
 ```js
 {
-  "version": "x.y-prerelease", // required
+  "version": "x.y-prerelease", // required (unless the "inherit" field is set to true and a parent version.json file sets this.)
   "assemblyVersion": "x.y", // optional. Use when x.y for AssemblyVersionAttribute differs from the default version property.
   "buildNumberOffset": "zOffset", // optional. Use when you need to add/subtract a fixed value from the computed build number.
+  "semVer1NumericIdentifierPadding": 4, // optional. Use when your -prerelease includes numeric identifiers and need semver1 support.
+  "nugetPackageVersion": {
+     "semVer": 1 // optional. Set to either 1 or 2 to control how the NuGet package version string is generated. Default is 1.
+  },
   "publicReleaseRefSpec": [
     "^refs/heads/master$", // we release out of master
-    "^refs/tags/v\\d\\.\\d" // we also release tags starting with vN.N
+    "^refs/tags/v\\d+\\.\\d+" // we also release tags starting with vN.N
   ],
   "cloudBuild": {
     "setVersionVariables": true,
@@ -37,12 +44,18 @@ The content of the version.json file is a JSON serialized object with these prop
         "where": "buildMetadata"
       }
     }
-  }
+  },
+  "inherit": false // optional. Set to true in secondary version.json files used to tweak settings for subsets of projects.
 }
 ```
 
 The `x` and `y` variables are for your use to specify a version that is meaningful
 to your customers. Consider using [semantic versioning][semver] for guidance.
+You may optionally supply a third integer in the version (i.e. x.y.z),
+in which case the git version height is specified as the fourth integer,
+which only appears in certain version representations.
+Alternatively, you can include the git version height in the -prerelease tag using
+syntax such as: `1.2.3-beta.{height}`
 
 The optional -prerelease tag allows you to indicate that you are building prerelease software.
 

doc/vsix.md

@@ -8,6 +8,4 @@ the version calculated from your version.json file and git height.
 1. Install the Nerdbank.GitVersioning NuGet package into your VSIX-generating project.
 1. Open the `source.extension.vsixmanifest` file in a code editor
 and set the `PackageManifest/Metadata/Identity/@Version` attribute to this
-value: `|YourProjectName;GetBuildVersion|` where `YourProjectName` is
-obviously replaced with the actual project name (without extension) of your
-VSIX project.
+value: `|%CurrentProject%;GetBuildVersion|`

init.ps1

@@ -1,6 +1,6 @@
 <#
 .SYNOPSIS
-Restores all NuGet, NPM and Typings packages necessary to build this repository. 
+Restores all NuGet, NPM and Typings packages necessary to build this repository.
 #>
 [CmdletBinding(SupportsShouldProcess)]
 Param(
@@ -18,12 +18,7 @@ try {
         & "$toolsPath\Restore-NuGetPackages.ps1" -Path $_ -Verbosity Quiet
     }
 
-    # Restore VS solution dependencies
-    gci "$PSScriptRoot\src" -rec |? { $_.FullName.EndsWith('.sln') } |% {
-        & "$toolsPath\Restore-NuGetPackages.ps1" -Path $_.FullName -Verbosity Quiet
-    }
-
-    # Restore VS2017 style as well, since nuget 3.3 doesn't support it.
+    # Restore VS2017 style to get the rest of the projects.
     msbuild "$PSScriptRoot\src\NerdBank.GitVersioning.Tests\NerdBank.GitVersioning.Tests.csproj" /t:restore /v:minimal /m /nologo
 
     Write-Host "Restoring NPM packages..." -ForegroundColor Yellow

readme.md

@@ -2,6 +2,7 @@
 
 [![Build status](https://ci.appveyor.com/api/projects/status/94wwito7ifg57d65/branch/master?svg=true)](https://ci.appveyor.com/project/AArnott/nerdbank-gitversioning/branch/master)
 [![NuGet package](https://img.shields.io/nuget/v/Nerdbank.GitVersioning.svg)](https://nuget.org/packages/Nerdbank.GitVersioning)
+[![NuGet downloads](https://img.shields.io/nuget/dt/Nerdbank.GitVersioning.svg)](https://nuget.org/packages/Nerdbank.GitVersioning)
 [![NPM package](https://img.shields.io/npm/v/nerdbank-gitversioning.svg)](https://www.npmjs.com/package/nerdbank-gitversioning)
 [![Join the chat at https://gitter.im/AArnott/Nerdbank.GitVersioning](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/AArnott/Nerdbank.GitVersioning?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 

src/.editorconfig

@@ -0,0 +1,78 @@
+# EditorConfig is awesome:http://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Don't use tabs for indentation.
+[*]
+indent_style = space
+# (Please don't specify an indent_size here; that has too many unintended consequences.)
+
+# Code files
+[*.{cs,csx,vb,vbx}]
+indent_size = 4
+
+# Xml project files
+[*.{csproj,vbproj,vcxproj,vcxproj.filters,proj,projitems,shproj}]
+indent_size = 2
+
+# Xml config files
+[*.{props,targets,ruleset,config,nuspec,resx,vsixmanifest,vsct}]
+indent_size = 2
+
+# JSON files
+[*.json]
+indent_size = 2
+
+# Dotnet code style settings:
+[*.{cs,vb}]
+# Sort using and Import directives with System.* appearing first
+dotnet_sort_system_directives_first = true
+# Use "this." and "Me." everywhere
+dotnet_style_qualification_for_field = true:warning
+dotnet_style_qualification_for_property = true:warning
+dotnet_style_qualification_for_method = true:warning
+dotnet_style_qualification_for_event = true:warning
+
+# Use language keywords instead of framework type names for type references
+dotnet_style_predefined_type_for_locals_parameters_members = true:suggestion
+dotnet_style_predefined_type_for_member_access = true:suggestion
+
+# Suggest more modern language features when available
+dotnet_style_object_initializer = true:suggestion
+dotnet_style_collection_initializer = true:suggestion
+dotnet_style_coalesce_expression = true:suggestion
+dotnet_style_null_propagation = true:suggestion
+dotnet_style_explicit_tuple_names = true:suggestion
+
+# CSharp code style settings:
+[*.cs]
+# Prefer "var" everywhere
+csharp_style_var_for_built_in_types = false:none
+csharp_style_var_when_type_is_apparent = true:none
+csharp_style_var_elsewhere = false:none
+
+# Prefer method-like constructs to have a block body
+csharp_style_expression_bodied_methods = true:suggestion
+csharp_style_expression_bodied_constructors = true:suggestion
+csharp_style_expression_bodied_operators = true:suggestion
+
+# Prefer property-like constructs to have an expression-body
+csharp_style_expression_bodied_properties = true:suggestion
+csharp_style_expression_bodied_indexers = true:suggestion
+csharp_style_expression_bodied_accessors = true:suggestion
+
+# Suggest more modern language features when available
+csharp_style_pattern_matching_over_is_with_cast_check = true:suggestion
+csharp_style_pattern_matching_over_as_with_null_check = true:suggestion
+csharp_style_inlined_variable_declaration = true:suggestion
+csharp_style_throw_expression = true:suggestion
+csharp_style_conditional_delegate_call = true:suggestion
+
+# Newline settings
+csharp_new_line_before_open_brace = all
+csharp_new_line_before_else = true
+csharp_new_line_before_catch = true
+csharp_new_line_before_finally = true
+csharp_new_line_before_members_in_object_initializers = true
+csharp_new_line_before_members_in_anonymous_types = true