diff options
author | dagood <dagood@microsoft.com> | 2015-12-10 20:16:38 +0300 |
---|---|---|
committer | dagood <dagood@microsoft.com> | 2015-12-11 20:23:58 +0300 |
commit | dd8f820304c72d1f90ee1a471b2a1c466616b47f (patch) | |
tree | 54c29c2a0d5ae44a11c3e5cb3b7a4d229ab8e998 | |
parent | f9da3b4af08214764a51b2331f3595ffaf162abe (diff) |
Update buildtools, add updating-validate target, add documentation.
-rw-r--r-- | Documentation/README.md | 1 | ||||
-rw-r--r-- | Documentation/project-docs/project-nuget-dependencies.md | 54 | ||||
-rw-r--r-- | build.proj | 14 | ||||
-rw-r--r-- | dir.props | 2 | ||||
-rw-r--r-- | src/.nuget/packages.Unix.config | 2 | ||||
-rw-r--r-- | src/.nuget/packages.Windows_NT.config | 2 |
6 files changed, 65 insertions, 10 deletions
diff --git a/Documentation/README.md b/Documentation/README.md index 049103e0db..3a673dd009 100644 --- a/Documentation/README.md +++ b/Documentation/README.md @@ -34,6 +34,7 @@ Project Docs - [Strong Name Signing](project-docs/strong-name-signing.md) - [Open Source Signing](project-docs/oss-signing.md) - [Repo Organization](project-docs/repo-organization.md) +- [Project NuGet Dependencies](project-docs/project-nuget-dependencies.md) Coding Guidelines ================= diff --git a/Documentation/project-docs/project-nuget-dependencies.md b/Documentation/project-docs/project-nuget-dependencies.md new file mode 100644 index 0000000000..1a6c17146b --- /dev/null +++ b/Documentation/project-docs/project-nuget-dependencies.md @@ -0,0 +1,54 @@ +Project NuGet Dependencies +========================== + +In CoreFX, dependencies on NuGet packages are stored in `project.json` files. `project.lock.json` files shouldn't be checked in to this repository. + +A dependency must be for a specific version of a package: no floating (\*) dependencies are used. This ensures builds are repeatable. CoreFX also has some rules for certain groups of packages that need to stay in sync: for example, all prerelease `System.*` packages must use the same prerelease version. These rules are validated during a build step, so a local build or continuous integration will catch any mistakes. + +As a historical note, `project.json` files in CoreFX previously had floating dependencies and `project.lock.json` files were checked in to lock the version for repeatable package restore. This was changed during pull request [#4894](https://github.com/dotnet/corefx/pull/4894). + +Dependency version validation +----------------------------- + +The dependencies in each CoreFX project.json file are validated by a few rules to ensure package versions across the repository stay in sync. These rules are in `dir.props`, as `ValidationPattern` items. Each `ValidationPattern` item includes a regular expression that matches a set of package identities and metadata describing which version is expected for that regular expression. The metadata must be one of these: + +* `ExpectedPrerelease`: a prerelease version is expected, but any major, minor, and patch versions are fine. For example, an `ExpectedVersion` of `rc-12345` is valid for `1.0.0-rc-12345`, `5.4.3-rc-12345`, or any other `*-rc-12345` +* `ExpectedVersion`: the full version string needs to match exactly. An example is `1.0.0-prerelease`. + +Errors you can expect from failed dependency version validation are like the following: + + error : Dependency validation error: for System.IO 4.0.10-rc2-10000 in src\System.Collections\tests\project.json package prerelease is 'rc2-10000', but expected 'rc2-23604' for packages matching '^((System\..*)|(Microsoft\.CSharp)|(Microsoft\.NETCore.*)|(Microsoft\.Win32\..*)|(Microsoft\.VisualBasic))(?<!TestData)$' + + error : Dependency validation error: for System.Linq 4.0.0-beta-* in src\System.Collections\tests\project.json package prerelease is 'beta-', but expected 'rc2-23604' for packages matching '^((System\..*)|(Microsoft\.CSharp)|(Microsoft\.NETCore.*)|(Microsoft\.Win32\..*)|(Microsoft\.VisualBasic))(?<!TestData)$' + error : Floating dependency detected: System.Linq 4.0.0-beta-* in src\System.Collections\tests\project.json + + error : Dependency validation error: for xunit 2.0.0 in src\System.Collections\tests\project.json package version is '2.0.0' but expected '2.1.0' for packages matching '^xunit$' + +To fix these, you can manually modify the `project.json` files mentioned or automatically fix them using the `UpdateInvalidPackageVersions` target described in the next section. + +Upgrading a package dependency +------------------------------ + +To update a package that isn't validated by a rule, simply change the project.json file. + +To update a package that is validated, follow these steps: + +1. Edit `ValidationPattern` item(s) in `dir.props` in the CoreFX root. +2. Run the dependency update target in the repository root using this command: + + build.cmd /t:UpdateInvalidPackageVersions + +3. Commit the automated updates in an independent commit, isolating them from other changes. This makes pull requests easier to review. + +The `UpdateInvalidPackageVersions` target looks through all dependencies, using the validation rules to update any invalid versions. The build prints out which dependencies are updated and which project.json files are written. + +Recovering from a non-existent prerelease dependency +---------------------------------------------------- + +Sometimes upgrading the prerelease version can make `project.json` files contain dependencies that don't exist. For example, if you update a rule's valid prerelease from `beta-100` to `beta-200`, but around `beta-150` a stable version of `System.Foo` was released and prereleases changed from `1.0.0-beta-...` to `1.1.0-beta-...`, automatic package updating would result in a dependency on `1.0.0-beta-200`. However, only `1.1.0-beta-200` exists. + +To fix this, use the `UpdatePackageDependencyVersion` target: + + msbuild /t:UpdatePackageDependencyVersion /p:PackageId=System.Foo;OldVersion=1.0.0-beta-200;NewVersion=1.1.0-beta-200 + +This updates the `System.Foo` version in all `project.json` files in CoreFX. diff --git a/build.proj b/build.proj index a02cd0d9ee..3bea980525 100644 --- a/build.proj +++ b/build.proj @@ -46,16 +46,16 @@ ValidationPatterns="@(ValidationPattern)" /> </Target> + <Target Name="UpdateInvalidPackageVersions"> + <ValidateProjectDependencyVersions ProjectJsons="@(ProjectJsonFiles)" + ProhibitFloatingDependencies="$(ProhibitFloatingDependencies)" + ValidationPatterns="@(ValidationPattern)" + UpdateInvalidDependencies="true" /> + </Target> + <!-- Tasks from buildtools for easy project.json dependency updates --> - <UsingTask TaskName="UpdatePrereleaseDependencies" AssemblyFile="$(BuildToolsTaskDir)Microsoft.DotNet.Build.Tasks.dll" /> <UsingTask TaskName="UpdatePackageDependencyVersion" AssemblyFile="$(BuildToolsTaskDir)Microsoft.DotNet.Build.Tasks.dll" /> - <Target Name="UpdatePrereleaseDependencies"> - <UpdatePrereleaseDependencies ProjectJsons="@(ProjectJsonFiles)" - OldPrerelease="$(OldPrerelease)" - NewPrerelease="$(NewPrerelease)" /> - </Target> - <Target Name="UpdatePackageDependencyVersion"> <UpdatePackageDependencyVersion ProjectJsons="@(ProjectJsonFiles)" PackageId="$(PackageId)" @@ -10,7 +10,7 @@ <!-- Build Tools Versions --> <PropertyGroup> - <BuildToolsVersion>1.0.25-prerelease-00131</BuildToolsVersion> + <BuildToolsVersion>1.0.25-prerelease-00133</BuildToolsVersion> <DnxVersion>1.0.0-rc2-16128</DnxVersion> <DnxPackageName Condition="'$(DnxPackageName)' == '' and '$(OsEnvironment)'!='Unix'">dnx-coreclr-win-x86.$(DnxVersion)</DnxPackageName> <DnxPackageName Condition="'$(DnxPackageName)' == '' and '$(OsEnvironment)'=='Unix'">dnx-mono.$(DnxVersion)</DnxPackageName> diff --git a/src/.nuget/packages.Unix.config b/src/.nuget/packages.Unix.config index 38edbb9fa0..96fb7ebe32 100644 --- a/src/.nuget/packages.Unix.config +++ b/src/.nuget/packages.Unix.config @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <packages> - <package id="Microsoft.DotNet.BuildTools" version="1.0.25-prerelease-00131" /> + <package id="Microsoft.DotNet.BuildTools" version="1.0.25-prerelease-00133" /> <package id="Microsoft.DotNet.BuildTools.ApiTools" version="1.0.0-prerelease" /> <package id="dnx-mono" version="1.0.0-rc2-16128" /> <package id="Microsoft.Net.ToolsetCompilers" version="1.0.0-rc3-20150510-01" /> diff --git a/src/.nuget/packages.Windows_NT.config b/src/.nuget/packages.Windows_NT.config index 8d69196008..d8be64cce8 100644 --- a/src/.nuget/packages.Windows_NT.config +++ b/src/.nuget/packages.Windows_NT.config @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <packages> - <package id="Microsoft.DotNet.BuildTools" version="1.0.25-prerelease-00131" /> + <package id="Microsoft.DotNet.BuildTools" version="1.0.25-prerelease-00133" /> <package id="dnx-coreclr-win-x86" version="1.0.0-rc2-16128" /> <package id="Microsoft.DotNet.BuildTools.ApiTools" version="1.0.0-prerelease" /> </packages> |