Skip to content

Commit 6194d9b

Browse files
ysolomchenkoCodeBlanch
ysolomchenko
and
CodeBlanch
authored
[repo] How to maintain PublicApi files (open-telemetry#5823)
Co-authored-by: Mikel Blanchard <[email protected]>
1 parent 2b43c09 commit 6194d9b

File tree

1 file changed

+82
-27
lines changed

1 file changed

+82
-27
lines changed

‎CONTRIBUTING.md‎

Lines changed: 82 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -59,33 +59,88 @@ of Windows.
5959
* Visual Studio 2022+ or Visual Studio Code
6060
* .NET Framework 4.6.2+
6161

62-
### Public API
63-
64-
It is critical to keep public API surface small and clean. This repository is
65-
using `Microsoft.CodeAnalysis.PublicApiAnalyzers` to validate the public APIs.
66-
This analyzer will check if you changed a public property/method so the change
67-
will be easily spotted in pull request. It will also ensure that OpenTelemetry
68-
doesn't expose APIs outside of the library primary concerns like a generic
69-
helper methods.
70-
71-
#### How to enable and configure
72-
73-
* Create a folder in your project called `.publicApi` with the frameworks that
74-
as folders you target.
75-
* Create two files called `PublicAPI.Shipped.txt` and `PublicAPI.Unshipped.txt`
76-
in each framework that you target.
77-
* Add the following lines to your csproj:
78-
79-
```xml
80-
<ItemGroup>
81-
<AdditionalFiles Include=".publicApi\$(TargetFramework)\PublicAPI.Shipped.txt" />
82-
<AdditionalFiles Include=".publicApi\$(TargetFramework)\PublicAPI.Unshipped.txt" />
83-
</ItemGroup>
84-
```
85-
86-
* Use
87-
[IntelliSense](https://docs.microsoft.com/visualstudio/ide/using-intellisense)
88-
to update the publicApi files.
62+
### Public API Validation
63+
64+
It is critical to **NOT** make breaking changes to public APIs which have been
65+
released in stable builds. We also strive to keep a minimal public API surface.
66+
This repository is using
67+
[Microsoft.CodeAnalysis.PublicApiAnalyzers](https://github.com/dotnet/roslyn-analyzers/blob/main/src/PublicApiAnalyzers/PublicApiAnalyzers.Help.md)
68+
and [Package
69+
validation](https://learn.microsoft.com/dotnet/fundamentals/apicompat/package-validation/overview)
70+
to validate public APIs.
71+
72+
* `Microsoft.CodeAnalysis.PublicApiAnalyzers` will validate public API
73+
changes/additions against a set of "public API files" which capture the
74+
shipped/unshipped public APIs. These files must be maintained manually (not
75+
recommended) or by using tooling/code fixes built into the package (see below
76+
for details).
77+
78+
Public API files are also used to perform public API reviews by repo
79+
approvers/maintainers before releasing stable builds.
80+
81+
* `Package validation` will validate public API changes/additions against
82+
previously released NuGet packages.
83+
84+
This is performed automatically by the build/CI
85+
[package-validation](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/.github/workflows/package-validation.yml)
86+
workflow.
87+
88+
By default package validation is **NOT** run for local builds. To enable
89+
package validation in local builds set the `EnablePackageValidation` property
90+
to `true` in
91+
[Common.prod.props](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/build/Common.prod.props)
92+
(please do not check in this change).
93+
94+
#### Working with Microsoft.CodeAnalysis.PublicApiAnalyzers
95+
96+
##### Update public API files when writing code
97+
98+
[IntelliSense](https://docs.microsoft.com/visualstudio/ide/using-intellisense)
99+
will [suggest
100+
modifications](https://github.com/dotnet/roslyn-analyzers/issues/3322#issuecomment-591031429)
101+
to the `PublicAPI.Unshipped.txt` file when you make changes. After reviewing
102+
these changes, ensure they are reflected across all targeted frameworks. You can
103+
do this by:
104+
105+
* Using the "Fix all occurrences in Project" feature in Visual Studio.
106+
107+
* Manually cycling through each framework using Visual Studio's target framework
108+
dropdown (in the upper right corner) and applying the IntelliSense
109+
suggestions.
110+
111+
> [!IMPORTANT]
112+
> Do **NOT** modify `PublicAPI.Shipped.txt` files. New features and bug fixes
113+
**SHOULD** only require changes to `PublicAPI.Unshipped.txt` files. If you
114+
have to modify a "shipped" file it likely means you made a mistake and broke a
115+
stable API. Typically only maintainers modify the `PublicAPI.Shipped.txt` file
116+
while performing stable releases. If you need help reach out to an approver or
117+
maintainer on Slack or open a draft PR.
118+
119+
##### Enable public API validation in new projects
120+
121+
1. If you are **NOT** using experimental APIs:
122+
* If your API is the same across all target frameworks:
123+
* You only need two files: `.publicApi/PublicAPI.Shipped.txt` and
124+
`.publicApi/PublicAPI.Unshipped.txt`.
125+
* If your APIs differ between target frameworks:
126+
* Place the shared APIs in `.publicApi/PublicAPI.Shipped.txt` and
127+
`.publicApi/PublicAPI.Unshipped.txt`.
128+
* Create framework-specific files for API differences (e.g.,
129+
`.publicApi/net462/PublicAPI.Shipped.txt` and
130+
`.publicApi/net462/PublicAPI.Unshipped.txt`).
131+
132+
2. If you are using experimental APIs:
133+
* Follow the rules above, but create an additional layer in your folder
134+
structure:
135+
* For stable APIs: `.publicApi/Stable/*`.
136+
* For experimental APIs: `.publicApi/Experimental/*`.
137+
* The `Experimental` folder should contain APIs that are public only in
138+
pre-release builds. Typically the `Experimental` folder only contains
139+
`PublicAPI.Unshipped.txt` files as experimental APIs are never shipped
140+
stable.
141+
142+
Example folder structure can be found
143+
[here](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Api/.publicApi).
89144

90145
## Pull Requests
91146

0 commit comments

Comments
 (0)