Merge Development to Master - For work on documentation

.github/prompts/csharp-docs.prompt.md

@@ -0,0 +1,63 @@
+---
+agent: 'agent'
+tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems']
+description: 'Ensure that C# types are documented with XML comments and follow best practices for documentation.'
+---
+
+# C# Documentation Best Practices
+
+- Public members should be documented with XML comments.
+- It is encouraged to document internal members as well, especially if they are complex or not self-explanatory.
+
+## Guidance for all APIs
+
+- Use `<summary>` to provide a brief, one sentence, description of what the type or member does. Start the summary with a present-tense, third-person verb.
+- Use `<remarks>` for additional information, which can include implementation details, usage notes, or any other relevant context.
+- Use `<see langword>` for language-specific keywords like `null`, `true`, `false`, `int`, `bool`, etc.
+- Use `<c>` for inline code snippets.
+- Use `<example>` for usage examples on how to use the member.
+  - Use `<code>` for code blocks. `<code>` tags should be placed within an `<example>` tag. Add the language of the code example using the `language` attribute, for example, `<code language="csharp">`.
+- Use `<see cref>` to reference other types or members inline (in a sentence).
+- Use `<seealso>` for standalone (not in a sentence) references to other types or members in the "See also" section of the online docs.
+- Use `<inheritdoc/>` to inherit documentation from base classes or interfaces.
+  - Unless there is major behavior change, in which case you should document the differences.
+
+## Methods
+
+- Use `<param>` to describe method parameters.
+  - The description should be a noun phrase that doesn't specify the data type.
+  - Begin with an introductory article.
+  - If the parameter is a flag enum, start the description with "A bitwise combination of the enumeration values that specifies...".
+  - If the parameter is a non-flag enum, start the description with "One of the enumeration values that specifies...".
+  - If the parameter is a Boolean, the wording should be of the form "`<see langword="true" />` to ...; otherwise, `<see langword="false" />`.".
+  - If the parameter is an "out" parameter, the wording should be of the form "When this method returns, contains .... This parameter is treated as uninitialized.".
+- Use `<paramref>` to reference parameter names in documentation.
+- Use `<typeparam>` to describe type parameters in generic types or methods.
+- Use `<typeparamref>` to reference type parameters in documentation.
+- Use `<returns>` to describe what the method returns.
+  - The description should be a noun phrase that doesn't specify the data type.
+  - Begin with an introductory article.
+  - If the return type is Boolean, the wording should be of the form "`<see langword="true" />` if ...; otherwise, `<see langword="false" />`.".
+
+## Constructors
+
+- The summary wording should be "Initializes a new instance of the <Class> class [or struct].".
+
+## Properties
+
+- The `<summary>` should start with:
+  - "Gets or sets..." for a read-write property.
+  - "Gets..." for a read-only property.
+  - "Gets [or sets] a value that indicates whether..." for properties that return a Boolean value.
+- Use `<value>` to describe the value of the property.
+  - The description should be a noun phrase that doesn't specify the data type.
+  - If the property has a default value, add it in a separate sentence, for example, "The default is `<see langword="false" />`".
+  - If the value type is Boolean, the wording should be of the form "`<see langword="true" />` if ...; otherwise, `<see langword="false" />`. The default is ...".
+
+## Exceptions
+
+- Use `<exception cref>` to document exceptions thrown by constructors, properties, indexers, methods, operators, and events.
+- Document all exceptions thrown directly by the member.
+- For exceptions thrown by nested members, document only the exceptions users are most likely to encounter.
+- The description of the exception describes the condition under which it's thrown.
+  - Omit "Thrown if ..." or "If ..." at the beginning of the sentence. Just state the condition directly, for example "An error occurred when accessing a Message Queuing API."

.github/workflows/build-deploy-docs.yml

@@ -0,0 +1,77 @@
+name: Build and Deploy DocFX
+
+on:
+  push:
+    branches: [ 'master' ]
+    paths:
+      - 'docs/**'
+      - 'README.md'
+      # Uncomment this if API docs changes should trigger a rebuild of the documentation
+      # - 'src/**'
+      - '.github/workflows/build-deploy-docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build-docs:
+    if: ${{ github.ref == 'refs/heads/master' }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: |
+            8.x
+            9.x
+      # - name: Show dotnet version
+      #   run: |
+      #     dotnet --list-sdks
+      #     dotnet --list-runtimes
+
+      # - name: Restore dependencies before docs deployment as recommended by docfx
+      #   run: dotnet restore ./src/Mapster.sln
+
+      # - name: Build with dotnet
+      #   run: dotnet build ./src/Mapster.sln
+
+      # - name: Run tests on .NET 9.0
+      #   run: dotnet test --verbosity normal ./src/Mapster.sln
+
+      - name: Install DocFX as .NET tool
+        run: |
+          dotnet tool update -g docfx
+
+      - name: Build docfx site
+        working-directory: docs
+        run: docfx docfx.json
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload entire repository
+          path: 'docs/_site'
+
+  deploy-docs:
+    needs: build-docs
+    if: ${{ needs.build-docs.result == 'success' && github.ref == 'refs/heads/master' }}
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/conventional-commits.yml

@@ -0,0 +1,21 @@
+name: Conventional Commits
+
+on:
+  pull_request:
+    branches:
+      - master
+      - development
+      - release/* 
+
+env:
+  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+jobs:
+  commitsar:
+    name: Validate for conventional commits
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v1
+      - name: Run commitsar
+        uses: aevea/commitsar@v0.20.2

.github/workflows/dotnet-buildandtest.yml

@@ -12,16 +12,19 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Setup .NET
-      uses: actions/setup-dotnet@v3
+      uses: actions/setup-dotnet@v4
       with:
-        dotnet-version: 7.0.x
+        dotnet-version: |
+          8.x
+          9.x
+          10.x
     - name: Show dotnet version
       run: |
         dotnet --list-sdks
         dotnet --list-runtimes
     - name: Build with dotnet
       run: dotnet build ./src/Mapster.sln
-    - name: Run tests on .NET 7.0
+    - name: Run tests on .NET 10.0
       run: dotnet test --verbosity normal ./src/Mapster.sln

.gitignore

@@ -131,6 +131,9 @@ packages/
 # This line needs to be after the ignore of the build folder (and the packages folder if the line above has been uncommented)
 !packages/build/
 
+# Not ignore packages folder in docs folder
+!docs/articles/packages/
+
 # Windows Azure Build Output
 csx/
 *.build.csdef
@@ -181,3 +184,7 @@ project.lock.json
 /src/.vs
 /.vs
 src/.idea
+
+# VS Code settings
+.vscode/launch.json
+.vscode/tasks.json

.markdownlint.jsonc

@@ -0,0 +1,16 @@
+{
+	"$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/v0.38.0/schema/markdownlint-config-schema.json",
+	"default": true,
+	"line-length": false,
+	"commands-show-output": false,
+	"no-bare-urls": false,
+	"no-inline-html": false,
+	"no-duplicate-heading": false,
+	"no-emphasis-as-heading": false,
+	// Headers must start at the beginning of the line - false positive in some cases where it makes sense.
+	"MD023": false,
+	// First line in a file should be a top-level heading - false positive for include files.
+	"MD041": false,
+	// Link fragments should be valid - false positive for docfx tabs
+	"MD051": false
+}

.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+  "recommendations": [
+    "DavidAnson.vscode-markdownlint",
+    "streetsidesoftware.code-spell-checker-cspell-bundled-dictionaries",
+    "ms-vscode.powershell",
+    "joshbolduc.commitlint"
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,8 @@
+{
+    "files.associations": {
+        "*.agent.md": "chatagent",
+        "*.instructions.md": "instructions",
+        "*.prompt.md": "prompt",
+        "docfx.json": "jsonc"
+    }
+}

CONTRIBUTING.md

@@ -0,0 +1,36 @@
+![Mapster Icon](https://raw.githubusercontent.com/MapsterMapper/Mapster/master/docs/images/mapster-logo.svg)
+
+# Contributing to Mapster
+
+Thank you for your interest in contributing! We welcome contributions from the community.
+
+## How to Contribute
+
+1. **Fork the repository** and create your branch from [`development`](https://github.com/MapsterMapper/Mapster/tree/development)
+2. **Make your changes** following the existing code style
+3. **Write tests** using [MSTest](https://docs.microsoft.com/en-us/dotnet/core/testing/unit-testing-with-mstest) and [xUnit](https://xunit.net/) to ensure your changes work correctly
+4. **Document your code** with XML comments and update [docs/articles/](./docs/articles/) if needed following the [DocFX](https://dotnet.github.io/docfx/) guidelines
+5. **Commit with clear messages** following [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) (e.g., `feat:`, `fix:`, `docs:`)
+6. **Submit a pull request** with a description of your changes
+
+## Reporting Issues
+
+Found a bug or have a feature request? Please [open an issue](https://github.com/MapsterMapper/Mapster/issues) with:
+
+- Clear description of the problem or request
+- Steps to reproduce (for bugs)
+- Code samples if applicable
+- Environment details (Mapster version, .NET version)
+
+For questions, use [GitHub Discussions](https://github.com/MapsterMapper/Mapster/discussions).
+
+## Development Guidelines
+
+- Follow existing code conventions
+- Add XML documentation for public APIs
+- Write unit tests for new features and bug fixes
+- Keep code clean, well-documented, and tested
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).