This page provides to-do lists for some common tasks one may encounter while contributing to Mapperly.
To introduce a new diagnostic follow these steps:
- Ensure no existing diagnostic in
Riok.Mapperly.Diagnostics.DiagnosticDescriptors.csmatches the new use case.
- Create a new public static readonly entry following the existing naming and formatting style,
as ID use
<NUMBER>being the highest already used number plus one. The highest used number can be found in
AnalyzerReleases.Shipped.mdas there may be removed diagnostics which are not present in
DiagnosticDescriptorsanymore but which should still not be used for new diagnostics.
- Add the new diagnostic to
AnalyzerReleases.Shipped.md(Mapperly does not use the
- Add a unit test generating and asserting the added diagnostic (use
It is not necessary to update the
Analyzer diagnostics documentation page manually,
as it is generated automatically on the basis of the
New public API
If new public API surface is introduced in
add the new API to the
PublicAPI.Shipped.txt file directly.
Mapperly does not use the
Add support for a new roslyn version
To support a new roslyn version via multi targeting follow these steps (see also architecture/roslyn multi targeting):
- Include the new version in
- Create a new file
src/Riok.Mapperlysimilar to the existing ones and define constants and include dependencies as needed.
- Update the default
- Update the
- Adjust the .NET version matrix of the
integration-testGitHub Actions job (defined in
.github/workflows/test.yml) to include a dotnet version which is based on the added Roslyn version.
- Adjust the .NET version in the
global.jsonfile as needed.
- Add the new version in
- If generated code changes based on the new Roslyn version,
VersionedSnapshotAttributes as needed.
- Adjust the documentation as needed.
- Add new preprocessor constants to
- Add new GitHub required checks as needed (needs to be done by a maintainer).
Mapperly Mappings use Roslyn syntax trees.
RoslynQuoter and SharpLab
are fantastic tools to understand and work with Roslyn syntax trees.
Microsoft.CodeAnalysis.CSharp.SyntaxFactory classes help building these syntax trees.