From c17ca908da49f2a60d979ee37b6f006daf17c507 Mon Sep 17 00:00:00 2001 From: Rafael Vuijk Date: Sun, 9 Aug 2026 01:31:20 +0000 Subject: [PATCH] Retire the public-API doc and its dead analyzer settings AGENTS.md carried a standing note that RS1617Errors.md describes adding public members to a PublicApi.*.txt, that neither those files nor the analyzer wanting them are in the tree, and to delete or rewrite it when in there anyway. This is that. The half of it that is still true -- anything added for the library's own purposes is not public -- moves into coding_rules.md beside the other two rules of its kind, with a note that nothing enforces it any more, so it reads as a rule to follow rather than one to be caught by. The half about RS0016 and PublicApi.*.txt goes. Sources/.editorconfig set RS0016 and RS0017 to error. The Microsoft.CodeAnalysis.PublicApiAnalyzers package that raises them is referenced nowhere, so those two lines have been configuring an analyzer that is not installed; they go too. The contributor index pointed at the deleted file as item 5 and now points at coding_rules.md, which had no entry at all despite being the file AGENTS.md sends people to for the sealed-or-abstract rule. Docs and build configuration only. Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 8 +++++--- Sources/.editorconfig | 6 ------ Sources/AngouriMath/Docs/Contributing/README.md | 4 ++-- .../AngouriMath/Docs/Contributing/RS1617Errors.md | 11 ----------- .../AngouriMath/Docs/Contributing/coding_rules.md | 14 +++++++++++++- 5 files changed, 20 insertions(+), 23 deletions(-) delete mode 100644 Sources/AngouriMath/Docs/Contributing/RS1617Errors.md diff --git a/AGENTS.md b/AGENTS.md index 3a26113e5..778677d14 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -367,9 +367,11 @@ are short, and a stale one is worse than none — if you change what a file desc | [`WhatsNew/version_performance_control.md`](Sources/AngouriMath/Docs/WhatsNew/version_performance_control.md) | the inter-version performance table, and how to add a column | | `Sources/Analyzers/` | the custom analyzers, including the static-field one behind `[ConstantField]` | -`Docs/Contributing/RS1617Errors.md` is the one exception: it describes adding public members to a -`PublicApi.*.txt`, and neither those files nor the analyzer that wanted them are in the tree any -more. Do not follow it; delete or rewrite it if you are in there anyway. +Anything added for the library's own purposes is not `public` — see +[`Contributing/coding_rules.md`](Sources/AngouriMath/Docs/Contributing/coding_rules.md). Nothing +checks that any more: the `PublicApiAnalyzers` package that required every public member to be +listed in a `PublicApi.*.txt` is gone from the tree, so it is a rule to follow rather than one to +be caught by. ## Where the work is diff --git a/Sources/.editorconfig b/Sources/.editorconfig index 5ba88dd3d..cbb98c043 100644 --- a/Sources/.editorconfig +++ b/Sources/.editorconfig @@ -3,12 +3,6 @@ # CS0660: 'IntervalPiece' defines operator == or operator != but does not override Object.Equals(object o) dotnet_diagnostic.CS0660.severity = suggestion -# RS0016: some public method is not mentioned as public API -dotnet_diagnostic.RS0016.severity = error - -# RS0017: some method mentioned as public API is not public -dotnet_diagnostic.RS0017.severity = error - # Missing header warning dotnet_diagnostic.IDE0073.severity = warning diff --git a/Sources/AngouriMath/Docs/Contributing/README.md b/Sources/AngouriMath/Docs/Contributing/README.md index e3028dceb..850139295 100644 --- a/Sources/AngouriMath/Docs/Contributing/README.md +++ b/Sources/AngouriMath/Docs/Contributing/README.md @@ -12,8 +12,8 @@ If you aren't sure about what to add, you may want to check the current projects 3. Improve parser 4. Transformations — the layer the 1.x entry points sit on, and how to add the next rule set or transformation -5. Adding a public member — out of date; the `PublicApi.*.txt` files - and the analyzer that required them are no longer in the tree +5. Coding rules — sealed-or-abstract, immutability, and what may be + made `public` See also BREAKING-CHANGES.md, where a change that makes the same input give a different answer is recorded, and diff --git a/Sources/AngouriMath/Docs/Contributing/RS1617Errors.md b/Sources/AngouriMath/Docs/Contributing/RS1617Errors.md deleted file mode 100644 index 93148283e..000000000 --- a/Sources/AngouriMath/Docs/Contributing/RS1617Errors.md +++ /dev/null @@ -1,11 +0,0 @@ -## Public methods and classes - -When adding a class for purposes inside the library, you must not mark them as `public`. -When adding a method, make sure that it's either not `public` or the class you are adding the method to -is not `public`. - -However, if you intentionally want to add a publicly-exposed functional, you will get the -RS0016 error. - -That means you're required to report about this public method or class. You can simply add it to the -PublicApi.*.txt file or hit `ctrl + .` to do it. \ No newline at end of file diff --git a/Sources/AngouriMath/Docs/Contributing/coding_rules.md b/Sources/AngouriMath/Docs/Contributing/coding_rules.md index c5e8f2177..bf5bff144 100644 --- a/Sources/AngouriMath/Docs/Contributing/coding_rules.md +++ b/Sources/AngouriMath/Docs/Contributing/coding_rules.md @@ -8,4 +8,16 @@ Each inheritable type is either abstract or sealed. ### Immutability -It should be guaranteed that the user cannot change fields of a record which is inherited from `Entity`. \ No newline at end of file +It should be guaranteed that the user cannot change fields of a record which is inherited from `Entity`. + +### Visibility + +Anything added for the library's own purposes is not `public`. A type used internally stays +`internal`; a method added to a `public` type stays `internal` or `private` unless it is meant for +callers. `public` is a promise that +[BREAKING-CHANGES.md](../../../../BREAKING-CHANGES.md) then has to keep, so it is worth making +deliberately rather than by default. + +This used to be enforced by the `PublicApiAnalyzers` package, which required every public member to +be listed in a `PublicApi.*.txt`. Neither the package nor those files are in the tree any more, so +nothing checks it — which makes it a rule to follow rather than one to be caught by. \ No newline at end of file