From b4b5eb1aa52ad770767ddc5d3633cf44a992565d Mon Sep 17 00:00:00 2001 From: SadPencil Date: Thu, 25 Sep 2025 01:13:39 +0800 Subject: [PATCH 1/3] Enhance documentation on updating reference source for new APIs Updated documentation to emphasize implementing API modifications and updating the reference source when adding new APIs. --- docs/coding-guidelines/adding-api-guidelines.md | 6 ++++++ docs/workflow/building/libraries/README.md | 2 ++ 2 files changed, 8 insertions(+) diff --git a/docs/coding-guidelines/adding-api-guidelines.md b/docs/coding-guidelines/adding-api-guidelines.md index 07e256cbef044e..efc05d3cd853f1 100644 --- a/docs/coding-guidelines/adding-api-guidelines.md +++ b/docs/coding-guidelines/adding-api-guidelines.md @@ -29,6 +29,12 @@ should be added to `net10.0`. [More Information on TargetFrameworks](https://lea ## Making the changes in repo +**Implement your API modification** + - Implement your API modification in the appropriate library project. + +**Update the reference source** + - [Update the reference source](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/updating-ref-source.md) for the library. + **Update tests** - Add new `TargetFramework` to the ```TargetFrameworks```. - Add new test code following [conventions](project-guidelines.md#code-file-naming-conventions) for new files to that are specific to the new target framework. diff --git a/docs/workflow/building/libraries/README.md b/docs/workflow/building/libraries/README.md index 6916fcd6e9d255..e7d76e5c2340a1 100644 --- a/docs/workflow/building/libraries/README.md +++ b/docs/workflow/building/libraries/README.md @@ -263,4 +263,6 @@ If changes to the library include any API incompatibilities, calling `dotnet bui In rare cases where these are expected (e.g. updating APIs previously shipped only in preview or as experimental), the errors may be suppressed. This can be done by following the directions in the error to invoke `dotnet build` (if the project isn't packable) or `dotnet pack` (if the project is packable) with an additional `/p:ApiCompatGenerateSuppressionFile=true` argument. +**Note:** If you are simply adding new APIs, you should not suppress API compatibility errors. Instead, make sure you have updated [the reference source](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/updating-ref-source.md) for the library. + See https://learn.microsoft.com/dotnet/fundamentals/apicompat/overview for more details. From eec33ea499494ea885d4456d2342f42a5e8ee97d Mon Sep 17 00:00:00 2001 From: SadPencil Date: Thu, 25 Sep 2025 01:36:19 +0800 Subject: [PATCH 2/3] Apply suggestion from @GerardSmit Co-authored-by: Gerard Smit --- docs/coding-guidelines/adding-api-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/coding-guidelines/adding-api-guidelines.md b/docs/coding-guidelines/adding-api-guidelines.md index efc05d3cd853f1..473ebf67b7483f 100644 --- a/docs/coding-guidelines/adding-api-guidelines.md +++ b/docs/coding-guidelines/adding-api-guidelines.md @@ -33,7 +33,7 @@ should be added to `net10.0`. [More Information on TargetFrameworks](https://lea - Implement your API modification in the appropriate library project. **Update the reference source** - - [Update the reference source](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/updating-ref-source.md) for the library. + - [Update the reference source](updating-ref-source.md) for the library. **Update tests** - Add new `TargetFramework` to the ```TargetFrameworks```. From 8a3080676d5cf020bb6fb311bcf82af7310eb7a8 Mon Sep 17 00:00:00 2001 From: SadPencil Date: Thu, 25 Sep 2025 01:36:25 +0800 Subject: [PATCH 3/3] Apply suggestion from @GerardSmit Co-authored-by: Gerard Smit --- docs/workflow/building/libraries/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/workflow/building/libraries/README.md b/docs/workflow/building/libraries/README.md index e7d76e5c2340a1..f342fe8e848ed1 100644 --- a/docs/workflow/building/libraries/README.md +++ b/docs/workflow/building/libraries/README.md @@ -263,6 +263,6 @@ If changes to the library include any API incompatibilities, calling `dotnet bui In rare cases where these are expected (e.g. updating APIs previously shipped only in preview or as experimental), the errors may be suppressed. This can be done by following the directions in the error to invoke `dotnet build` (if the project isn't packable) or `dotnet pack` (if the project is packable) with an additional `/p:ApiCompatGenerateSuppressionFile=true` argument. -**Note:** If you are simply adding new APIs, you should not suppress API compatibility errors. Instead, make sure you have updated [the reference source](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/updating-ref-source.md) for the library. +**Note:** If you are simply adding new APIs, you should not suppress API compatibility errors. Instead, make sure you have updated [the reference source](../../../coding-guidelines/updating-ref-source.md) for the library. See https://learn.microsoft.com/dotnet/fundamentals/apicompat/overview for more details.