Api compat (Azure#9568)

AzureSDKAutomation · Jan 23, 2020 · a0b3009 · a0b3009
1 parent 53928d4
commit a0b3009
Show file tree

Hide file tree

Showing 12 changed files with 103 additions and 4 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -117,9 +117,24 @@ If for any reason there is an update to the build tools, you will then need to f
 ### Testing Against Latest Versions of Client Libraries
 In some cases, you might want to test against the latest versions of the client libraries. i.e. version not yet published to nuget. For this scenario you should make use of the `UseProjectReferenceToAzureClients` property which when set to `true` will switch all package references for client libraries present in the build to project references. This result in testing against the current version of the libraries in the repo. e.g. `dotnet test eng\service.proj /p:ServiceDirectory=eventhub --filter TestCategory!=Live /p:UseProjectReferenceToAzureClients=true`
 
-## Public API changes
+## Public API additions
 
-If you make a public API change `eng\Export-API.ps1` script has to be run to update public API listings.
+If you make a public API addition, the `eng\Export-API.ps1` script has to be run to update public API listings.
+
+## API Compatibility Verification
+
+.NET is using the [ApiCompat tool](https://github.com/dotnet/arcade/tree/master/src/Microsoft.DotNet.ApiCompat) to enforce API compatibility between versions. Builds of GA'ed libraries will fail locally and in CI if there are breaking changes.
+
+### How it works
+We use a dummy project called [ApiCompat](https://github.com/Azure/azure-sdk-for-net/tree/master/eng/ApiCompat/ApiCompat.csproj) to enforce API compatibility between the GA'ed libraries and the most recent version available on Nuget. This project includes package references to all GA'ed libraries and to Microsoft.DotNet.ApiCompat.
+Each listed library package is restored from Nuget via the package references listed in the `ApiCompat.csproj` file, in combination with the version listed for that package in [eng/Packages.Data.props](https://github.com/Azure/azure-sdk-for-net/blob/master/eng/Packages.Data.props).
+The `ApiCompatVerification` target defined in `ApiCompat.csproj` is referenced in the [eng/Directory.Build.Data.targets](https://github.com/Azure/azure-sdk-for-net/blob/master/eng/Directory.Build.Data.targets) which causes this target to be executed for each csproj that has the `EnableApiCompat` parameter set to true. The `EnableApiCompat` parameter defaults to the value of the `IsShippingClientLibrary` parameter, which is defined in [eng/Directory.Build.Data.props](https://github.com/Azure/azure-sdk-for-net/blob/master/eng/Directory.Build.Data.props).
+
+### Adding a new GA'ed library
+To include add a new GA'ed library in the `ApiCompatVerification` target, add a package reference for the library to the `ApiCompat.csproj` file. You will also need to include the latest GA version of the library in [eng/Packages.Data.props](https://github.com/Azure/azure-sdk-for-net/blob/master/eng/Packages.Data.props). 
+
+### Releasing a new version of a GA'ed libary
+Since the [eng/Packages.Data.props](https://github.com/Azure/azure-sdk-for-net/blob/master/eng/Packages.Data.props) is currently maintained manually, you will need to update the version number for your library in this file when releasing a new version.
 
 ## Dev Feed
 We publish nightly built packages to a dev feed which can be consumed by adding the dev feed blob storage as a package source in Visual Studio. 

diff --git a/eng/ApiCompat/ApiCompat.csproj b/eng/ApiCompat/ApiCompat.csproj
@@ -0,0 +1,50 @@
+<Project Sdk="Microsoft.NET.Sdk" DefaultTargets="ApiCompatVerification">
+  <!--This project is used to enforce API compatibility between the GA'ed libraries and the most recent version available on Nuget. The most recent
+  version is restored from Nuget via the package references below. The ApiCompatVerification target, specified below, is referenced in the
+  eng/Directory.Build.Data.targets file which causes this target to be executed for each csproj that has the EnableApiCompat parameter set to true.
+  The EnableApiCompat parameter defaults to the value of the IsShippingClientLibrary parameter, which is defined in the eng/Directory.Build.Data.props file.-->
+  <PropertyGroup>
+    <TargetFramework>netstandard2.0</TargetFramework>
+    <RunApiCompatForSrc>true</RunApiCompatForSrc>
+    <IntermediateOutputPath>$(IntermediateOutputPath)/$(TargetPackageName)</IntermediateOutputPath>    
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.DotNet.ApiCompat" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Core" />
+    <PackageReference Include="Azure.Data.AppConfiguration" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Azure.Security.KeyVault.Certificates" />
+    <PackageReference Include="Azure.Security.KeyVault.Keys" />
+    <PackageReference Include="Azure.Security.KeyVault.Secrets" />
+    <PackageReference Include="Azure.Storage.Blobs" />
+    <PackageReference Include="Azure.Storage.Blobs.Batch" />
+    <PackageReference Include="Azure.Storage.Common" />
+    <PackageReference Include="Azure.Storage.Files.Shares" />
+    <PackageReference Include="Azure.Storage.Queues" />
+    <PackageReference Include="Microsoft.Extensions.Azure" />
+  </ItemGroup>
+
+  <Import Project="..\Packages.Data.props" />
+
+  <Target Name="ApiCompatVerification" DependsOnTargets="_ResolveResolvedMatchingContract;$(TargetsTriggeredByCompilation)">
+  </Target>
+
+  <Target Name="_ResolveResolvedMatchingContract" DependsOnTargets="ResolveReferences">
+    <PropertyGroup>
+      <TargetPackageDll Condition="'%(ResolvedCompileFileDefinitions.NuGetPackageId)' == '$(TargetPackageName)'" >%(ResolvedCompileFileDefinitions.Identity)</TargetPackageDll>
+    </PropertyGroup>
+
+    <ItemGroup>
+      <ResolvedMatchingContract Include="$(TargetPackageDll)" />
+      <_DependencyDirectories Include="$(TargetOutputPath)" />
+      <ReferencePath Remove="$(TargetPackageDll)" />
+    </ItemGroup>
+    <Error Condition="'@(ResolvedMatchingContract)' == ''"
+             Text="Unable to find dll for $(TargetPackageName). Make sure it is included in list of Package References if the ApiCompatVerification target (defined in eng/ApiCompat/ApiCompat.csproj) is intended to run for this package. If ApiCompatVerification should not be run, set the EnableApiCompat parameter to false in the csproj file." />
+    <Message Text="Running ApiCompatVerification against $(TargetPackageDll) using assemblies from $(TargetOutputPath)" Importance="High" />
+  </Target>
+</Project>
diff --git a/eng/ApiCompat/Directory.Build.targets b/eng/ApiCompat/Directory.Build.targets
@@ -0,0 +1,6 @@
+<Project>
+
+    <!-- Avoid actually building anything -->
+    <Target Name="CoreBuild" />
+
+</Project>
diff --git a/eng/Directory.Build.Data.props b/eng/Directory.Build.Data.props
@@ -45,6 +45,7 @@
     <EnableFxCopAnalyzers Condition="'$(IsShippingClientLibrary)' == 'true'">true</EnableFxCopAnalyzers>
     <EnableStyleCopAnalyzers Condition="'$(EnableStyleCopAnalyzers)' == '' and '$(IsClientLibrary)' == 'true'">true</EnableStyleCopAnalyzers>
     <GenerateAPIListing Condition="'$(IsShippingClientLibrary)' == 'true'">true</GenerateAPIListing>
+    <EnableApiCompat Condition="'$(EnableApiCompat)' == '' and '$(IsShippingClientLibrary)' == 'true'">true</EnableApiCompat>
   </PropertyGroup>
 
   <!-- CodeAnalysis RuleSet -->

diff --git a/eng/Directory.Build.Data.targets b/eng/Directory.Build.Data.targets
@@ -63,6 +63,11 @@
   <ItemGroup>
     <PackageReference Include="Microsoft.SourceLink.GitHub" PrivateAssets="All" />
   </ItemGroup>
+
+  <!-- Enable ApiCompat  -->
+  <ItemGroup>
+    <ProjectReference Include="$(RepoRoot)/eng/ApiCompat/ApiCompat.csproj" ReferenceOutputAssembly="false" BuildReference="false" Condition="'$(EnableApiCompat)' == 'true'" />
+  </ItemGroup>
 
   <PropertyGroup>
     <ImportDefaultReferences Condition="'$(ImportDefaultReferences)' == ''">true</ImportDefaultReferences>
@@ -116,5 +121,12 @@
            Text="When UseProjectReferenceToAzureClients=true all Azure.* references should be Project References, but the following are not [@(ShouldBeProjectReference)]" />
   </Target>
 
+   <Target Name="RunApiCompat" AfterTargets="CoreBuild" Condition="'$(EnableApiCompat)' == 'true'">
+    <MSBuild
+      Projects="$(MSBuildThisFileDirectory)/ApiCompat/ApiCompat.csproj"
+      Properties="TargetPackageName=$(PackageId);TargetOutputPath=$(IntermediateOutputPath)"
+     />
+  </Target>
+
   <Import Project="$(CentralPackageVersionPackagePath)\Sdk.targets" />
 </Project>
diff --git a/eng/Packages.Data.props b/eng/Packages.Data.props
@@ -9,11 +9,18 @@
   <ItemGroup>
     <PackageReference Update="ApprovalTests" Version="3.0.22" />
     <PackageReference Update="ApprovalUtilities" Version="3.0.22" />
+    <PackageReference Update="Azure.Data.AppConfiguration" Version="1.0.0" />
     <PackageReference Update="Azure.Core" Version="1.0.1" />
     <PackageReference Update="Azure.Identity" Version="1.1.0" />
-    <PackageReference Update="Azure.Security.KeyVault.Secrets" Version="4.0.0" />
+    <PackageReference Update="Azure.Security.KeyVault.Secrets" Version="4.0.1" />
+    <PackageReference Update="Azure.Security.KeyVault.Certificates" Version="4.0.0" />
+    <PackageReference Update="Azure.Security.KeyVault.Keys" Version="4.0.1" />
     <PackageReference Update="Azure.Messaging.EventHubs" Version="5.0.0-preview.6" />
-    <PackageReference Update="Azure.Storage.Blobs" Version="12.0.0" />
+    <PackageReference Update="Azure.Storage.Blobs" Version="12.2.0" />
+    <PackageReference Update="Azure.Storage.Blobs.Batch" Version="12.1.1" />
+    <PackageReference Update="Azure.Storage.Common" Version="12.1.1" />
+    <PackageReference Update="Azure.Storage.Files.Shares" Version="12.0.1" />
+    <PackageReference Update="Azure.Storage.Queues" Version="12.1.1" />
     <PackageReference Update="BenchmarkDotNet" Version="0.11.5" />
     <PackageReference Update="FsCheck.Xunit" Version="2.14.0" />
     <PackageReference Update="Microsoft.AspNetCore.Server.Kestrel" Version="2.2.0" />
@@ -40,6 +47,8 @@
     <PackageReference Update="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="2.6.1" />
     <PackageReference Update="Microsoft.CodeAnalysis.FxCopAnalyzers" Version="2.6.2" />
     <PackageReference Update="Microsoft.CodeAnalysis" Version="2.3.0" />
+    <PackageReference Update="Microsoft.DotNet.ApiCompat" Version="5.0.0-beta.19552.1" />
+    <PackageReference Update="Microsoft.Extensions.Azure" Version="1.0.0" />
     <PackageReference Update="Microsoft.Extensions.Configuration.Abstractions" Version="2.1.0" />
     <PackageReference Update="Microsoft.Extensions.Configuration.Binder" Version="2.1.0" />
     <PackageReference Update="Microsoft.Extensions.Configuration.Json" Version="1.0.2" />

diff --git a/...enthub/Azure.Messaging.EventHubs.Processor/src/Azure.Messaging.EventHubs.Processor.csproj b/...enthub/Azure.Messaging.EventHubs.Processor/src/Azure.Messaging.EventHubs.Processor.csproj
@@ -5,6 +5,7 @@
     <PackageTags>Azure;Event Hubs;EventHubs;.NET;Event Processor;EventProcessor;$(PackageCommonTags)</PackageTags>
     <TargetFrameworks>$(RequiredTargetFrameworks)</TargetFrameworks>
     <EnableFxCopAnalyzers>false</EnableFxCopAnalyzers>
+    <EnableApiCompat>false</EnableApiCompat>
   </PropertyGroup>
 
   <ItemGroup>

diff --git a/sdk/eventhub/Azure.Messaging.EventHubs/src/Azure.Messaging.EventHubs.csproj b/sdk/eventhub/Azure.Messaging.EventHubs/src/Azure.Messaging.EventHubs.csproj
@@ -5,6 +5,7 @@
     <PackageTags>Azure;Event Hubs;EventHubs;.NET;AMQP;IoT;$(PackageCommonTags)</PackageTags>
     <TargetFrameworks>$(RequiredTargetFrameworks)</TargetFrameworks>
     <EnableFxCopAnalyzers>false</EnableFxCopAnalyzers>
+    <EnableApiCompat>false</EnableApiCompat>
   </PropertyGroup>
 
   <ItemGroup>

diff --git a/sdk/storage/Azure.Storage.Blobs.Cryptography/src/Azure.Storage.Blobs.Cryptography.csproj b/sdk/storage/Azure.Storage.Blobs.Cryptography/src/Azure.Storage.Blobs.Cryptography.csproj
@@ -15,6 +15,7 @@
       Microsoft Azure Storage REST API Reference - https://docs.microsoft.com/en-us/rest/api/storageservices/
       REST API Reference for Blob Service - https://docs.microsoft.com/en-us/rest/api/storageservices/blob-service-rest-api
     </Description>
+    <EnableApiCompat>false</EnableApiCompat>
   </PropertyGroup>
   <ItemGroup>
     <ProjectReference Include="$(MSBuildThisFileDirectory)..\..\Azure.Storage.Common\src\Azure.Storage.Common.csproj" />

diff --git a/sdk/storage/Azure.Storage.Files.DataLake/src/Azure.Storage.Files.DataLake.csproj b/sdk/storage/Azure.Storage.Files.DataLake/src/Azure.Storage.Files.DataLake.csproj
@@ -16,6 +16,7 @@
       REST API Reference for Data Lake - https://docs.microsoft.com/en-us/rest/api/storageservices/datalakestoragegen2/filesystem
     </Description>
     <GenerateAPIListing>false</GenerateAPIListing>
+    <EnableApiCompat>false</EnableApiCompat>
   </PropertyGroup>
   <ItemGroup>
     <PackageReference Include="System.Text.Json" />

diff --git a/sdk/template/Azure.Template/src/Azure.Template.csproj b/sdk/template/Azure.Template/src/Azure.Template.csproj
@@ -8,5 +8,6 @@
     <Version>1.0.2-preview.4</Version>
     <PackageTags>Azure Template</PackageTags>
     <TargetFrameworks>$(RequiredTargetFrameworks)</TargetFrameworks>
+    <EnableApiCompat>false</EnableApiCompat>
   </PropertyGroup>
 </Project>
diff --git a/sdk/textanalytics/Azure.AI.TextAnalytics/src/Azure.AI.TextAnalytics.csproj b/sdk/textanalytics/Azure.AI.TextAnalytics/src/Azure.AI.TextAnalytics.csproj
@@ -8,6 +8,7 @@
     <GenerateAPIListing>false</GenerateAPIListing>
     <TargetFrameworks>$(RequiredTargetFrameworks)</TargetFrameworks>
     <NoWarn>$(NoWarn);3021</NoWarn>
+    <EnableApiCompat>false</EnableApiCompat>
   </PropertyGroup>
 
   <ItemGroup>