Merge master into openapi

.config/dotnet-tools.json

@@ -15,7 +15,7 @@
       ]
     },
     "dotnet-reportgenerator-globaltool": {
-      "version": "5.2.1",
+      "version": "5.2.2",
       "commands": [
         "reportgenerator"
       ]

.github/CONTRIBUTING.md

@@ -39,7 +39,7 @@ When you are creating an enhancement suggestion, please include as many details
 
 - **Use a clear and descriptive title** for the issue to identify the suggestion.
 - **Provide a step-by-step description of the suggested enhancement** in as many details as possible.
-- **Provide specific examples to demonstrate the usage.** Include copy/pasteable snippets which you use in those examples, as [Markdown code blocks](https://docs.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks).
+- **Provide specific examples to demonstrate the usage.** Include copy/pasteable snippets which you use in those examples as [Markdown code blocks](https://docs.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks).
 - **Describe the current behavior and explain which behavior you expected to see instead** and why.
 - **Explain why this enhancement would be useful** to most users and isn't something that can or should be implemented in your API project directly.
 - **Verify that your enhancement does not conflict** with the [JSON:API specification](https://jsonapi.org/).
@@ -56,7 +56,7 @@ Please follow these steps to have your contribution considered by the maintainer
 - Follow all instructions in the template. Don't forget to add tests and update documentation.
 - After you submit your pull request, verify that all status checks are passing. In release builds, all compiler warnings are treated as errors, so you should address them before push.
 
-We use [CSharpGuidelines](https://csharpcodingguidelines.com/) as our coding standard (with a few minor exceptions). Coding style is validated during PR build, where we inject an extra settings layer that promotes various suggestions to warning level. This ensures a high-quality codebase without interfering too much when editing code.
+We use [CSharpGuidelines](https://csharpcodingguidelines.com/) as our coding standard. Coding style is validated during PR build, where we inject an extra settings layer that promotes various IDE suggestions to warning level. This ensures a high-quality codebase without interfering too much while editing code.
 You can run the following [PowerShell scripts](https://github.com/PowerShell/PowerShell/releases) locally:
 - `pwsh ./inspectcode.ps1`: Scans the code for style violations and opens the result in your web browser.
 - `pwsh ./cleanupcode.ps1 [branch-name-or-commit-hash]`: Reformats the codebase to match with our configured style, optionally only changed files since the specified branch (usually master).
@@ -86,13 +86,39 @@ public sealed class AppDbContext : DbContext
 }
 ```
 
+### Pull request workflow
+
+Please follow the steps and guidelines below for a smooth experience.
+
+Authors:
+- When opening a new pull request, create it in **Draft** mode.
+- After you've completed the work *and* all checks are green, click the **Ready for review** button.
+  - If you have permissions to do so, ask a team member for review.
+- Once the review has started, don't force-push anymore.
+- When you've addressed feedback from a conversation, mark it with a thumbs-up or add a some text.
+- Don't close a conversation you didn't start. The creator closes it after verifying the concern has been addressed.
+- Apply suggestions in a batch, instead of individual commits (to minimize email notifications).
+- Re-request review when you're ready for another round.
+- If you want to clean up your commits before merge, let the reviewer know in time. This is optional.
+
+Reviewers:
+- If you're unable to review within a few days, let the author know what to expect.
+- Use **Start a review** instead of **Add single comment** (to minimize email notifications).
+- Consider to use suggestions (the ± button).
+- Don't close a conversation you didn't start. Close the ones you opened after verifying the concern has been addressed.
+- Once approved, use a merge commit only if all commits are clean. Otherwise, squash them into a single commit.
+  A commit is considered clean when:
+    - It is properly documented and covers all aspects of an isolated change (code, style, tests, docs).
+    - Checking out the commit results in a green build.
+    - Having this commit show up in the history is helpful (and can potentially be reverted).
+
 ## Creating a release (for maintainers)
 
 - Verify documentation is up-to-date
-- Bump the package version in Directory.Build.props
+- Bump the package version in `Directory.Build.props`
 - Create a GitHub release
-- Update https://github.com/json-api-dotnet/JsonApiDotNetCore.MongoDb to consume the new version and release
-- Create a new branch in https://github.com/json-api-dotnet/MigrationGuide and update README.md in master
+- Update [JsonApiDotNetCore.MongoDb](https://github.com/json-api-dotnet/JsonApiDotNetCore.MongoDb) to consume the new version and release
+- Create a new branch in [MigrationGuide](https://github.com/json-api-dotnet/MigrationGuide) and update README.md in master, if major version change
 
 ## Backporting and hotfixes (for maintainers)
 
@@ -101,7 +127,7 @@ public sealed class AppDbContext : DbContext
   git checkout tags/v2.5.1 -b release/2.5.2
   ```
 - Cherrypick the merge commit: `git cherry-pick {git commit SHA}`
-- Bump the package version in Directory.Build.props
+- Bump the package version in `Directory.Build.props`
 - Make any other compatibility, documentation, or tooling related changes
 - Push the branch to origin and verify the build
 - Once the build is verified, create a GitHub release, tagging the release branch

docs/home/index.html

@@ -9,7 +9,7 @@
   <link href="favicon.ico" rel="icon">
   <link href="favicon.ico" rel="apple-touch-icon">
   <link href="https://fonts.googleapis.com/css?family=Open+Sans:300,300i,400,400i,600,600i,700,700i|Raleway:300,300i,400,400i,600,600i,700,700i" rel="stylesheet">
-  <link href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.5.0/css/bootstrap.css" rel="stylesheet">
+  <link href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.5.0/css/bootstrap.min.css" rel="stylesheet">
   <link href="https://unpkg.com/boxicons@2.0.7/css/boxicons.min.css" rel="stylesheet">
   <link href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.4.0/styles/default.min.css" rel="stylesheet">
   <link href="https://cdnjs.cloudflare.com/ajax/libs/aos/2.3.4/aos.css" rel="stylesheet">
@@ -22,7 +22,10 @@
       <div class="row">
         <div class="col-lg-7 pt-5 pt-lg-0 order-2 order-lg-1">
           <h1>JsonApiDotNetCore</h1>
-          <h2>A framework for building <a href="https://jsonapi.org/" target="_blank">JSON:API</a> compliant REST APIs using .NET Core and Entity Framework Core. Includes support for <a href="https://jsonapi.org/ext/atomic/" target="_blank">Atomic Operations</a>.</h2>
+          <h2>
+            A framework for building <a href="https://jsonapi.org/" target="_blank">JSON:API</a> compliant REST APIs using .NET Core and Entity Framework Core.
+            Includes support for <a href="https://jsonapi.org/ext/atomic/" target="_blank">Atomic Operations</a>.
+          </h2>
           <a href="#about" class="btn-get-started scrollto">Read more</a>
           <a href="../../getting-started/install.html" class="btn-get-started">Getting started</a>
           <a href="https://github.com/json-api-dotnet/JsonApiDotNetCore/" target="_blank" class="btn-get-started">Contribute on GitHub</a>
@@ -43,12 +46,13 @@ <h2>A framework for building <a href="https://jsonapi.org/" target="_blank">JSON
           <div class="col-lg-6 pt-5 pt-lg-0">
             <h3 data-aos="fade-up">Objectives</h3>
             <p data-aos="fade-up" data-aos-delay="100">
-              The goal of this library is to simplify the development of APIs that leverage the full range of features provided by the <a href="https://jsonapi.org/" target="_blank">JSON:API</a> specification.
+              The goal of this library is to simplify the development of APIs that leverage the full range of features
+              provided by the <a href="https://jsonapi.org/" target="_blank">JSON:API</a> specification.
               You just need to focus on defining the resources and implementing your custom business logic.
             </p>
             <div class="row">
               <div class="col-md-6" data-aos="fade-up" data-aos-delay="100">
-                <i class='bx bxs-package'></i>
+                <i class="bx bxs-package"></i>
                 <h4>Eliminate boilerplate</h4>
                 <p>We strive to eliminate as much boilerplate as possible by offering out-of-the-box features such as sorting, filtering and pagination.</p>
               </div>
@@ -69,28 +73,28 @@ <h2>Features</h2>
           <p>The following features are supported, from HTTP all the way down to the database</p>
         </div>
         <div class="row">
-          <div feature class="col-md-6 col-lg-3 d-flex align-items-stretch" data-aos="zoom-in" data-aos-delay="100" id='filter'>
+          <div feature class="col-md-6 col-lg-3 d-flex align-items-stretch" data-aos="zoom-in" data-aos-delay="100" id="filter">
             <div class="icon-box">
               <div class="icon"><i class="bx bxs-filter-alt"></i></div>
               <h4 class="title">Filtering</h4>
               <p class="description">Perform compound filtering using the <code>filter</code> query string parameter</p>
             </div>
           </div>
-          <div feature class="col-md-6 col-lg-3 d-flex align-items-stretch" data-aos="zoom-in" data-aos-delay="200" id='sort'>
+          <div feature class="col-md-6 col-lg-3 d-flex align-items-stretch" data-aos="zoom-in" data-aos-delay="200" id="sort">
             <div class="icon-box">
-              <div class="icon"><i class="bx bx-sort-z-a"></i></div>
+              <div class="icon"><i class="bx bx-sort-a-z"></i></div>
               <h4 class="title">Sorting</h4>
               <p class="description">Order resources on one or multiple attributes using the <code>sort</code> query string parameter</p>
             </div>
           </div>
-          <div feature class="col-md-6 col-lg-3 d-flex align-items-stretch" data-aos="zoom-in" data-aos-delay="300" id='pagination'>
+          <div feature class="col-md-6 col-lg-3 d-flex align-items-stretch" data-aos="zoom-in" data-aos-delay="300" id="pagination">
             <div class="icon-box">
               <div class="icon"><i class="bx bx-note"></i></div>
               <h4 class="title">Pagination</h4>
               <p class="description">Leverage the benefits of paginated resources with the <code>page</code> query string parameter</p>
             </div>
           </div>
-          <div feature class="col-md-6 col-lg-3 d-flex align-items-stretch" data-aos="zoom-in" data-aos-delay="400" id='selection'>
+          <div feature class="col-md-6 col-lg-3 d-flex align-items-stretch" data-aos="zoom-in" data-aos-delay="400" id="selection">
             <div class="icon-box">
               <div class="icon"><i class="bx bxs-select-multiple"></i></div>
               <h4 class="title">Sparse fieldset selection</h4>
@@ -99,30 +103,30 @@ <h4 class="title">Sparse fieldset selection</h4>
           </div>
         </div>
         <div class="row">
-          <div feature class="col-md-6 col-lg-3 d-flex align-items-stretch" data-aos="zoom-in" data-aos-delay="100" id='include'>
+          <div feature class="col-md-6 col-lg-3 d-flex align-items-stretch" data-aos="zoom-in" data-aos-delay="500" id="include">
             <div class="icon-box">
               <div class="icon"><i class="bx bxs-vector"></i></div>
               <h4 class="title">Relationship inclusion</h4>
               <p class="description">Side-load related resources of nested relationships using the <code>include</code> query string parameter</p>
             </div>
           </div>
-          <div feature class="col-md-6 col-lg-3 d-flex align-items-stretch" data-aos="zoom-in" data-aos-delay="100" id='security'>
+          <div feature class="col-md-6 col-lg-3 d-flex align-items-stretch" data-aos="zoom-in" data-aos-delay="600" id="security">
             <div class="icon-box">
-              <div class="icon"><i class='bx bxs-lock'></i></div>
+              <div class="icon"><i class="bx bxs-lock"></i></div>
               <h4 class="title">Security</h4>
-              <p class="description">Configure permissions, such as view/create/change/sort/filter of attributes and relationships</p>
+              <p class="description">Configure permissions, such as viewing, creating, modifying, sorting and filtering of attributes and relationships</p>
             </div>
           </div>
-          <div feature class="col-md-6 col-lg-3 d-flex align-items-stretch" data-aos="zoom-in" data-aos-delay="100" id='validation'>
+          <div feature class="col-md-6 col-lg-3 d-flex align-items-stretch" data-aos="zoom-in" data-aos-delay="700" id="validation">
             <div class="icon-box">
-              <div class="icon"><i class='bx bx-check-double'></i></div>
+              <div class="icon"><i class="bx bx-check-double"></i></div>
               <h4 class="title">Validation</h4>
-              <p class="description">Validate incoming requests using built-in ASP.NET Core <code>ModelState</code> validation, which works seamlessly with partial updates</p>
+              <p class="description">Validate incoming requests using built-in ASP.NET Model Validation, which works seamlessly with partial updates</p>
             </div>
           </div>
-          <div feature class="col-md-6 col-lg-3 d-flex align-items-stretch" data-aos="zoom-in" data-aos-delay="200" id='customizable'>
+          <div feature class="col-md-6 col-lg-3 d-flex align-items-stretch" data-aos="zoom-in" data-aos-delay="800" id="customizable">
             <div class="icon-box">
-              <div class="icon"><i class='bx bxs-category-alt'></i></div>
+              <div class="icon"><i class="bx bxs-category-alt"></i></div>
               <h4 class="title">Customizable</h4>
               <p class="description">Use various extensibility points to intercept and run custom code, besides just model annotations</p>
             </div>
@@ -139,7 +143,7 @@ <h2>Example usage</h2>
         <div class="row">
           <div code-example class="col-md-12 col-lg-12 d-flex d-flex justify-content-center" data-aos="zoom-in" data-aos-delay="100">
             <div class="icon-box code-example">
-              <div class="icon"><i class='bx bx-detail'></i></div>
+              <div class="icon"><i class="bx bx-detail"></i></div>
               <h4 class="title">Resource</h4>
               <pre>
 <code>#nullable enable
@@ -179,16 +183,16 @@ <h4 class="title">Resource</h4>
         <div class="row">
           <div code-example class="col-md-12 col-lg-12 d-flex d-flex justify-content-center" data-aos="zoom-in" data-aos-delay="100">
             <div class="icon-box code-example">
-              <div class="icon"><i class='bx bx-message-rounded-detail'></i></div>
+              <div class="icon"><i class="bx bx-message-rounded-detail"></i></div>
               <h4 class="title">Request</h4>
               <pre><code>GET /articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields[articles]=title,summary&include=author HTTP/1.1</code></pre>
             </div>
           </div>
         </div>
         <div class="row">
-          <div code-example class="col-md-12 col-lg-12 d-flex d-flex justify-content-center" data-aos="zoom-in" data-aos-delay="100">
+          <div code-example class="col-md-12 col-lg-12 d-flex d-flex justify-content-center" data-aos="zoom-in" data-aos-delay="200">
             <div class="icon-box code-example">
-              <div class="icon"><i class='bx bx-message-rounded-detail bx-flip-horizontal'></i></div>
+              <div class="icon"><i class="bx bx-message-rounded-detail bx-flip-horizontal"></i></div>
               <h4 class="title">Response</h4>
               <pre>
 <code>{
@@ -259,15 +263,15 @@ <h4 class="title">Response</h4>
           <h2>Sponsors</h2>
         </div>
         <div class="row justify-content-center">
-          <div sponsor class="col-md-4 col-lg-3 d-flex align-items-stretch justify-content-center aos-init aos-animate" data-aos="zoom-in" data-aos-delay="100" id="jetbrains">
-            <div class="icon-box d-flex align-items-center">
+          <div sponsor class="col-md-4 col-lg-3 d-flex align-items-stretch justify-content-center aos-init aos-animate" id="jetbrains">
+            <div class="icon-box d-flex align-items-center" data-aos="zoom-in" data-aos-delay="100">
               <div class="icon">
                 <img src="https://resources.jetbrains.com/storage/products/company/brand/logos/jb_beam.svg" alt="JetBrains Logo" style="width:150px">
               </div>
             </div>
           </div>
-          <div sponsor class="col-md-4 col-lg-3 d-flex align-items-stretch justify-content-center aos-init aos-animate" data-aos="zoom-in" data-aos-delay="100" id="araxis">
-            <div class="icon-box d-flex align-items-center" style="background-color: rgb(116, 125, 139)">
+          <div sponsor class="col-md-4 col-lg-3 d-flex align-items-stretch justify-content-center aos-init aos-animate" id="araxis">
+            <div class="icon-box d-flex align-items-center" style="background-color: rgb(116, 125, 139)" data-aos="zoom-in" data-aos-delay="200">
               <div class="icon">
                 <img src="https://www.araxis.com/theme/37/img/araxis-logo-lg.svg" alt="Araxis Logo" style="width:150px">
               </div>

docs/usage/writing/creating.md

@@ -16,8 +16,8 @@ POST /articles HTTP/1.1
 }
 ```
 
-When using client-generated IDs and only attributes from the request have changed, the server returns `204 No Content`.
-Otherwise, the server returns `200 OK`, along with the updated resource and its newly assigned ID.
+When using client-generated IDs and all attributes of the created resource are the same as in the request, the server
+returns `204 No Content`. Otherwise, the server returns `201 Created`, along with the stored attributes and its newly assigned ID.
 
 In both cases, a `Location` header is returned that contains the URL to the new resource.
 

package-versions.props

@@ -12,7 +12,7 @@
     <BenchmarkDotNetVersion>0.13.*</BenchmarkDotNetVersion>
     <BlushingPenguinVersion>1.0.*</BlushingPenguinVersion>
     <BogusVersion>35.2.*</BogusVersion>
-    <CodeAnalysisVersion>4.8.*</CodeAnalysisVersion>
+    <CodeAnalysisVersion>4.9.*</CodeAnalysisVersion>
     <CoverletVersion>6.0.*</CoverletVersion>
     <DapperVersion>2.1.*</DapperVersion>
     <FluentAssertionsVersion>6.12.*</FluentAssertionsVersion>