Clarify use of EnableApiCompat and its relation to /api/netstandard2.0.cs #11655
Conversation
CONTRIBUTING.md
Outdated
| ## Public API additions | ||
|
|
||
| If you make a public API addition, the `eng\scripts\Export-API.ps1` script has to be run to update public API listings. | ||
| If you make a public API addition, 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`. Note that this file is not required if each csproj in the library has the `EnableApiCompat` parameter set to false. |
There was a problem hiding this comment.
The API listing file is useful even when there was no release yet/library is in preview. It allows reviewers to easily see the public API changes made.
There was a problem hiding this comment.
Perhaps I should reword it to say ‘prior to preview’?
There was a problem hiding this comment.
Thank you for doing this. I agree with @pakrym and see the value in this for the reviewers too, I think the part that we can make more clear is that prior to having public packages, EnableApiCompat should be set to false, but Export-API still has to be called to generate the apis. Once there are public packages, EnableApiCompat should be flipped to true and the reference to that package should be added to ApiCompat.csproj.
There was a problem hiding this comment.
I've made some tweaks to the wording. Does that sound better?
4 participants
This clarification came out of some on-boarding feedback. Please validate that the statements are correct.