Skip to content

docs: updated docs to fix #31 #33

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kieronlanning merged 1 commit into from
Oct 2, 2026
Merged

docs: updated docs to fix #31 #33

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 24 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -486,7 +486,30 @@ Define `PURVIEW_SDK_EXCLUDE_EMBEDDED` only when your build already provides `Mic
Certain suffixes are automatically stripped from `RootNamespace` to avoid awkward namespace names like `Acme.MyProject.Core.Something`.

The current built-in stripping set is intentionally broader than the common examples and includes:
`SourceGeneration`, `SourceGenerators`, `SourceGenerator`, `ServiceDefaults`, `Infrastructure`, `Abstractions`, `ClientShared`, `Persistence`, `CodeFixers`, `DataAccess`, `Extensions`, `Generators`, `Analyzers`, `Contracts`, `Framework`, `Utilities`, `AppHost`, `Helpers`, `Library`, `Common`, `Shared`, `Infra`, `Utils`, `Core`, `Data`, `Host`, `Util`, `Lib`, `EF`, plus the known shared and shared-testing project names (`Shared*`, `SharedTesting*`).
`SourceGeneration`, `SourceGenerators`, `SourceGenerator`, `ServiceDefaults`, `Infrastructure`, `Abstractions`, `ClientShared`, `Persistence`, `CodeFixers`, `CodeFixes`, `DataAccess`, `Extensions`, `Generators`, `Analyzers`, `Contracts`, `Framework`, `Utilities`, `AppHost`, `Helpers`, `Library`, `Common`, `Shared`, `Infra`, `Utils`, `Core`, `Data`, `Host`, `Util`, `Lib`, `EF`, plus the known shared and shared-testing project names (`Shared*`, `SharedTesting*`).

### Keeping suffixes (opt a stripped suffix back in)

The strip list is authored as the `NamespaceRemoveSuffix` item type. To keep a suffix the SDK would
otherwise strip, remove the matching entry — this **must come after the `Sdk.props` import**, because
the items are declared there and only exist to be removed once the import has evaluated:

```xml
<Import Sdk="Purview.BuildSdk" Project="Sdk.props" />

<ItemGroup>
<!-- Keep the full SourceGenerators, CodeFixers and CodeFixes namespaces. -->
<NamespaceRemoveSuffix Remove="SourceGenerators" />
<NamespaceRemoveSuffix Remove="CodeFixers" />
<NamespaceRemoveSuffix Remove="CodeFixes" />
</ItemGroup>
```

This is useful for analyser/source-generator repos that deliberately name projects after the role — for
example `Purview.ZodSharp.SourceGenerators`, `Purview.ZodSharp.CodeFixers`, and `Purview.ZodSharp.CodeFixes` —
and want those roles to survive in the namespace rather than collapse into the parent `Purview.ZodSharp`
namespace. Only suffixes
present in the built-in list need removing; a suffix the SDK does not ship is already kept as-is.

### Extensions namespace rule (`PDS0002`)

Expand Down
25 changes: 24 additions & 1 deletion docs/wiki/Assembly-Name-Generation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,10 +43,33 @@ Certain suffixes are automatically stripped from `RootNamespace` to avoid awkwar

The built-in stripping set is broader than the common examples and includes:
`SourceGeneration`, `SourceGenerators`, `SourceGenerator`, `ServiceDefaults`, `Infrastructure`,
`Abstractions`, `ClientShared`, `Persistence`, `CodeFixers`, `DataAccess`, `Extensions`,
`Abstractions`, `ClientShared`, `Persistence`, `CodeFixers`, `CodeFixes`, `DataAccess`, `Extensions`,
`Generators`, `Analyzers`, `Contracts`, `Framework`, `Utilities`, `AppHost`, `Helpers`, `Library`,
`Common`, `Shared`, `Infra`, `Utils`, `Core`, `Data`, `Host`, `Util`, `Lib`, `EF`, plus the known
shared and shared-testing project names (`Shared*`, `SharedTesting*`).

### Keeping suffixes

The strip list is authored as the `NamespaceRemoveSuffix` item type. To keep a suffix the SDK would
otherwise strip, remove the matching entry — this **must come after the `Sdk.props` import**, because
the items are declared there and only exist to be removed once the import has evaluated:

```xml
<Import Sdk="Purview.BuildSdk" Project="Sdk.props" />

<ItemGroup>
<!-- Keep the full SourceGenerators, CodeFixers and CodeFixes namespaces. -->
<NamespaceRemoveSuffix Remove="SourceGenerators" />
<NamespaceRemoveSuffix Remove="CodeFixers" />
<NamespaceRemoveSuffix Remove="CodeFixes" />
</ItemGroup>
```

This is useful for analyser/source-generator repos that deliberately name projects after the role — for
example `Purview.ZodSharp.SourceGenerators`, `Purview.ZodSharp.CodeFixers`, and `Purview.ZodSharp.CodeFixes` —
and want those roles to survive in the namespace rather than collapse into the parent `Purview.ZodSharp`
namespace. Only suffixes
present in the built-in list need removing; a suffix the SDK does not ship is already kept as-is.

See [Project Naming Conventions](Project-Naming-Conventions.md) and
[InternalsVisibleTo](InternalsVisibleTo.md) for related naming behaviour.
1 change: 1 addition & 0 deletions docs/wiki/Configuration-Reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ See [Version Detection](Version-Detection.md) for the full resolution rules.
| `DisableProjectFileNamingConventionCheck` | `false` | Set to `true` to disable the validation that requires `MyProject\MyProject.csproj` naming alignment. |
| `DisableGenerateAssemblyInfoClass` | `false` | Set to `true` to disable the generated `AssemblyInfo` helper source. |
| `AutoIncludeUsings` | `true` | Controls SDK-added global usings for `NamespacePrefix` and `RootNamespace`. |
| `NamespaceRemoveSuffix` | *(built-in list)* | Item type listing the suffixes stripped from `RootNamespace`. Remove an entry **after** the `Sdk.props` import to keep that suffix in the namespace, e.g. `<NamespaceRemoveSuffix Remove="SourceGenerators" />`. See [Namespace stripping](Assembly-Name-Generation.md#namespace-stripping). |

## Repository metadata

Expand Down
1 change: 1 addition & 0 deletions src/src/BuildSdk/Sdk/Sdk.props
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@

<!-- 9 -->
<NamespaceRemoveSuffix Include="Analyzers" />
<NamespaceRemoveSuffix Include="CodeFixes" />
<NamespaceRemoveSuffix Include="Contracts" />
<NamespaceRemoveSuffix Include="Framework" />
<NamespaceRemoveSuffix Include="Utilities" />
Expand Down
11 changes: 11 additions & 0 deletions templates/Directory.Build.props
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,4 +26,15 @@
</PropertyGroup>

<Import Sdk="Purview.BuildSdk" Project="Sdk.props" />

<!--
Keep a suffix the SDK strips by default (must come AFTER the import above,
so the @(NamespaceRemoveSuffix) items exist to be removed). For example:

<ItemGroup>
<NamespaceRemoveSuffix Remove="SourceGenerators" />
<NamespaceRemoveSuffix Remove="CodeFixers" />
<NamespaceRemoveSuffix Remove="CodeFixes" />
</ItemGroup>
-->
</Project>
Loading