You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
OpenAPI.net is open to contributions. There are a couple of different recommended paths to get contributions into the released version of this library.
@@ -20,7 +20,32 @@ The best way to get started with a contribution is to start a dialog with the ow
20
20
21
21
## Submit pull requests for bug fixes and features
22
22
23
-
Feel free to submit a pull request with a linked issue against the __main__ branch. The main branch will be updated frequently.
23
+
Feel free to submit a pull request with a linked issue.
24
+
25
+
### Branches and support policy
26
+
27
+
Because one major consumer of these libraries is ASP.net, the support policy of this repository is aligned with [dotnet support policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core#lifecycle).
28
+
29
+
The following table outlines the mapping between package major versions, dotnet versions, and which contributions are accepted. As a consumer, make sure the version of this library your application is using is aligned with the version of ASP.net described in the table below.
30
+
31
+
| Major version | Branch | Supported [AspNetCore OpenAPI versions](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi)| Supported [Swashbuckle.AspNetCore version](https://www.nuget.org/packages/Swashbuckle.AspNetCore/)| Supported OpenAPI versions | Changes provided by Microsoft | Accepted contributions | End of support date |
| 3.X ² | main | not available | not available | 2.0, 3.0, 3.1, 3.2 | security, bugfixes and feature improvements | security, bugfixes and feature improvements | TBD |
36
+
37
+
> Notes:
38
+
>
39
+
> 1. This assumes that AspNetCore OpenAPI version 11 and above will adopt version 3 or above of this library, otherwise, it'd expand the support date for version 2 of this library.
40
+
> 2. This will be conditioned by new releases of OpenAPI, this library, ASP.NET and AspNetCore OpenAPI's adoption of new versions of this library.
41
+
> 3. This assumes that Swashbuckle.AspNetCore version 11 and above will adopt version 3 or above of this library.
42
+
43
+
### Multi-versions requirement for contributions
44
+
45
+
When contributing to the library, start by making a contribution to the main branch first, or the uppermost version it applies to. During the review process you'll be asked to demonstrate your contribution cannot apply to prior versions or to port your contribution to the branches for prior versions before the initial pull request can get merged.
46
+
47
+
This approach helps maintain a similar behavior across all versions under active support.
48
+
24
49
## Commit message format
25
50
26
51
To support our automated release process, pull requests are required to follow the [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/)
@@ -49,4 +74,53 @@ The recommended commit types used are:
49
74
-__ci__ for CI configuration file changes e.g. updating a pipeline
50
75
-__chore__ for miscallaneous non-sdk changesin the repo e.g. removing an unused file
51
76
52
-
Adding an exclamation mark after the commit type (`feat!`) or footer with the prefix __BREAKING CHANGE:__ will cause an increment of the _major_ version.
77
+
Adding an exclamation mark after the commit type (`feat!`) or footer with the prefix __BREAKING CHANGE:__ will cause an increment of the _major_ version.
78
+
79
+
## Updates to public API surface
80
+
81
+
Because we need to maintain a compatible public API surface within a major version, this project is using the public API analyzers to ensure no prior public API is changed/removed inadvertently.
82
+
83
+
This means that:
84
+
85
+
- All entries in an __Unshipped__ document need to be moved to the __Shipped__ document before any public release.
86
+
- All new APIs being added need to be __Unshipped__ document before the pull request can be merged, otherwise build will fail with a message like the example below.
87
+
88
+
```txt
89
+
Error: /home/runner/work/OpenAPI.NET/OpenAPI.NET/src/Microsoft.OpenApi/Models/OpenApiSecurityScheme.cs(39,46): error RS0016: Symbol 'OAuth2MetadataUrl.set' is not part of the declared public API (https://github.com/dotnet/roslyn-analyzers/blob/main/src/PublicApiAnalyzers/PublicApiAnalyzers.Help.md) [/home/runner/work/OpenAPI.NET/OpenAPI.NET/src/Microsoft.OpenApi/Microsoft.OpenApi.csproj::TargetFramework=net8.0]
90
+
```
91
+
92
+
### Update the unshipped document
93
+
94
+
To update the unshipped document, simply run the following commands
95
+
96
+
```shell
97
+
# add the missing public api entries
98
+
dotnet format --diagnostics RS0016
99
+
# discard changes to cs files to avoid creating conflicts
100
+
git checkout *.cs
101
+
```
102
+
103
+
### Move items from unshipped to unshipped document
104
+
105
+
```pwsh
106
+
. ./scripts/promoteUnshipped.ps1
107
+
```
108
+
109
+
> Note: the promotion of APIs is automated through the dedicated workflow and should result in pull requests being automatically opened.
110
+
111
+
## Updating the benchmark information
112
+
113
+
To ensure performance of the library does not degrade over time, we have continuous benchmarks running. You might see the continuous integration failing if your pull request changed any model under __src/Microsoft.OpenApi/Models__.
114
+
115
+
```txt
116
+
Benchmark result for EmptyApiSchema does not match the existing benchmark result (original!=new). Allocated bytes differ: 408 != 416
117
+
```
118
+
119
+
To update the benchmarks, run the following script:
120
+
121
+
```shell
122
+
cd performance/benchmark
123
+
dotnet run -c Release
124
+
```
125
+
126
+
Then commit the report files using a "chore" commit.
0 commit comments