docs: add contributor docs (#233)

Author: latonz

CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[email protected].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

CONTRIBUTING.md

@@ -0,0 +1,4 @@
+# Contributing
+
+We would love for you to contribute to Mapperly and help make it even better than it is today!
+Find information on how to contribute [in the docs](https://mapperly.riok.app/docs/contributing/).

README.md

@@ -47,6 +47,11 @@ dto.NumberOfSeats.Should().Be(10);
 
 [Read the docs](https://mapperly.riok.app/docs/getting-started/installation) for any further information.
 
+## How To Contribute
+
+We would love for you to contribute to Mapperly and help make it even better than it is today!
+Find information on how to contribute [in the docs](https://mapperly.riok.app/docs/contributing/).
+
 ## License
 
 Mapperly is [Apache 2.0](https://github.com/riok/mapperly/blob/main/LICENSE) licensed.

docs/README.md

@@ -0,0 +1,53 @@
+# Architecture
+
+Mapperly is an incremental .NET source generator implementation.
+Source generators are explained [here](https://github.com/dotnet/roslyn/blob/main/docs/features/source-generators.cookbook.md)
+and [here](https://github.com/dotnet/roslyn/blob/main/docs/features/incremental-generators.md).
+However, the incremental source generator of Mapperly is not yet optimal (see [#72](https://github.com/riok/mapperly/issues/72)).
+
+## Projects
+
+Mapperly is structured in two projects.
+`Riok.Mapperly.Abstractions` includes abstractions and attributes to be used by the application code,
+this is referenced by the source generator.
+`Riok.Mapperly` includes the implementation of the source generator.
+
+## Flow
+
+This describes the process implemented by Mapperly on a higher level.
+For each discovered `MapperAttribute` a new `DescriptorBuilder` is created.
+The `DescriptorBuilder` is responsible to build a `MapperDescriptor` which holds all the mappings.
+The `DescriptorBuilder` does this by following this process:
+1. Extracting the configuration from the attribute
+2. Extracting user implemented object factories
+3. Extracting user implemented and user defined mapping methods.
+   It instantiates a `User*Mapping` (eg. `UserDefinedNewInstanceMethodMapping`) for each discovered mapping method and adds it to the queue of mappings to work on.
+4. For each mapping in the queue the `DescriptorBuilder` tries to build its implementation bodies.
+   This is done by a so called `*MappingBodyBuilder`.
+   A mapping body builder tries to map each property from the source to the target.
+   To do this, it asks the `DescriptorBuilder` to create mappings for the according types.
+   To create a mapping from one type to another, the `DescriptorBuilder` loops through a set of `*MappingBuilder`s.
+   Each of the mapping builders try to create a mapping (an `ITypeMapping` implementation) for the asked type mapping by using
+   one approach on how to map types (eg. an explicit cast is implemented by the `ExplicitCastMappingBuilder`).
+   These mappings are queued in the queue of mappings which need the body to be built (currently body builders are only used for object to object (property-based) mappings).
+5. The `SourceEmitter` emits the code described by the `MapperDescriptor` and all its mappings.
+
+## Roslyn multi targeting
+
+Mapperly targets multiple Roslyn versions by building multiple NuGet packages
+and merging them together into a single one.
+Multi-targeting is needed to support new language features,
+such as required members introduced in C# 11,
+while still supporting older compiler versions.
+
+See `build/package.sh` for details.
+
+### Support a new roslyn version
+
+1. Include the new version in `roslyn_versions` in `build/package.sh`.
+2. Create a new file `Riok.Mapperly.Roslyn$(Version).props` in `src/Riok.Mapperly` similar to the existing ones
+   and define constants as needed.
+3. Update the default `ROSLYN_VERSION` in `src/Riok.Mapperly/Riok.Mapperly.csproj`.
+4. Adjust the .NET version matrix of the `integration-test` GitHub Actions job (defined in `.github/workflows/test.yml`)
+   to include a dotnet version which is based on the added Roslyn version.
+5. Adjust the .NET version in the `global.json` file as needed.

docs/docs/98-contributing/01-architecture.md

@@ -0,0 +1,53 @@
+# Tests and linting
+
+Mapperly is continuously tested by GitHub Actions.
+Tests are separated into integration and unit tests located in the `test` directory
+and use [xUnit](https://xunit.net/) and [VerifyTests](https://github.com/VerifyTests/Verify).
+You can run the tests by running
+```bash
+dotnet test
+```
+or by running the discovered tests in your IDE.
+
+## Unit tests
+
+The unit tests are located in the `tests/Riok.Mapperly.*.Tests` projects.
+These unit tests usually test exactly one unit of code or one type of mapping by isolating its code
+and verifying the reported diagnostics and the emitted code.
+Unit tests are easy to debug (you can debug them like any other code),
+but be reminded that these kind of tests only run on the latest supported target framework.
+
+## Integration tests
+
+The integration tests are located in `tests/Riok.Mapperly.IntegrationTests`.
+Integration tests are "a bit of everything" mappers.
+These tests run locally by referencing the source generator as an analyzer.
+In the CI pipeline, the integration tests reference the built NuGet package and
+are run on several supported target frameworks (including .NET 7.0 but also .NET Framework).
+
+Debugging integration tests is a lot harder than debugging unit tests.
+Therefore if an integration test needs to be debugged,
+it is often easier to implement an unit test for the to be tested behaviour
+and debug the unit test instead of the integration test.
+See also the [debugging documentation](./debugging) topic on how to debug Mapperly.
+
+## VerifyTests
+
+Several tests use [VerifyTests/Verify](https://github.com/VerifyTests/Verify)
+and [VerifyTests/Verify.SourceGenerators](https://github.com/VerifyTests/Verify.SourceGenerators)
+to verify reported diagnostics and snapshot emitted code.
+To work with the tests of Mapperly you may find it helpful to read the documentation of it.
+
+## Linting
+
+The source of Mapperly is linted with multiple dotnet analyzers.
+The format is checked with `dotnet format`.
+To fix issues locally run
+```bash
+dotnet format
+```
+
+and to verify there are no issues run
+```bash
+dotnet format --verify-no-changes
+```

docs/docs/98-contributing/02-tests.md

@@ -0,0 +1,22 @@
+# Debugging
+
+To debug the code generated by Mapperly just set a breakpoint in the generated code and you are ready to go.
+Check [here](../configuration/generated-source) on how to inspect the generated code.
+
+To debug the Mapperly in unit tests set a breakpoint
+in the code of Mappery which you want to debug and run the tests in debug mode.
+
+Since Mapperly runs integrated into the build pipeline,
+debugging integration tests and other applications needs some more effort.
+Mapperly uses a compile constant `DEBUG_SOURCE_GENERATOR` to determine whether to attach a debugger.
+If it is set, it tries to attach a debugger
+(it uses `Debugger.Launch()` on windows, on other operating systems it tries to launch JetBrains Rider)
+and waits for the connection of the debugger (for up to 30 seconds).
+If the automatic debugger attachment fails you can use these 30 seconds to attach the debugger manually
+(for vs 2022 see [attach to running processes](https://docs.microsoft.com/en-us/visualstudio/debugger/attach-to-running-processes-with-the-visual-studio-debugger?view=vs-2022)).
+You can use the `DefineConstants` dontet build or csproj parameter to define the `DEBUG_SOURCE_GENERATOR` constant
+or temporary comment the conditional attribute on `DebuggerUtil.AttachDebugger()`.
+
+For the debugger attachment with JetBrains Rider to work correctly,
+`Generate Shell Scripts` needs to be enabled in the JetBrains ToolBox
+and the generated shell scripts need to be on the path (Mapperly calls `rider attach-to-process {pid} {Mapperly-Sln-File}`).

docs/docs/98-contributing/03-debugging.md

@@ -0,0 +1,49 @@
+# Documentation
+
+The Mapperly documentation is built using [Docusaurus 2](https://docusaurus.io/)
+and is located in the `docs` directory.
+
+### Dependencies
+
+Docusaurus is based on the node ecosystem.
+A `.node-version` file provides the node version number to be used.
+This file can be interpreted by several node version managers (eg. [fnm](https://github.com/Schniz/fnm) or [nvm](https://github.com/nvm-sh/nvm)).
+Make sure you use a node version matching the version in `.node-version` for all following commands.
+
+To install documentation dependencies run:
+```bash
+npm i
+```
+
+### Update generated documentation
+
+To build the generated parts of the documentation
+(eg. the API documentation (located in `docs/99-api`), the table of analyzer rules, the samples, ...)
+ensure the dotnet solution is built or run `dontet build` in the solutions root directory.
+Then run the prebuild script:
+
+```bash
+npm run prebuild
+```
+
+To reflect changes, this command needs to be re-run each time the source of the generated output changes.
+
+### Local Development
+
+```bash
+npm run start
+```
+
+This command starts a local development server and opens up a browser window.
+Most changes are reflected live without having to restart the server.
+The documentation search does not work when using the local development server,
+as it depends on the statically built content (see [build](#build)).
+
+### Build
+
+```bash
+npm run build
+```
+
+This command generates static content into the `build` directory
+and can be served using any static contents hosting service or locally using `npm run serve`.