Skip to content

Commit 8b31ec0

Browse files
authored
Clarify use of EnableApiCompat and its relation to /api/netstandard2.0.cs (#11655)
* clarify use of EnableApiCompat and its relation to the netstandard2.0.cs file * update wording
1 parent 8a338eb commit 8b31ec0

File tree

1 file changed

+2
-2
lines changed

1 file changed

+2
-2
lines changed

CONTRIBUTING.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -137,7 +137,7 @@ In some cases, you might want to test against the latest versions of the client
137137

138138
## Public API additions
139139

140-
If you make a public API addition, the `eng\scripts\Export-API.ps1` script has to be run to update public API listings.
140+
If you make public API changes or additions, the `eng\scripts\Export-API.ps1` script has to be run to update public API listings. This generates a file in the library's directory similar to the example found in `sdk\template\Azure.Template\api\Azure.Template.netstandard2.0.cs`.
141141

142142
Running the script for a project in `sdk\tables` would look like this:
143143
```
@@ -151,7 +151,7 @@ eng\scripts\Export-API.ps1 tables
151151
### How it works
152152
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.
153153
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).
154-
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).
154+
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). For libraries that do not yet have a public package defined in `ApiCompat.csproj` for comparison, set `<EnableApiCompat>false</EnableApiCompat>` in the csproj.
155155

156156
### Adding a new GA'ed library
157157
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).

0 commit comments

Comments
 (0)