New docs #582

wojtek2288 · 2023-10-09T06:34:58Z

New documentation. If you want to check out how does it look visit: https://leancode-corelibrary--582.org.readthedocs.build/ (I would recommend reading it there).
This also uses old General section from README.md as new github README.md (with some small overview addition).
Removed Check links step from markdown lint check as it exceeded nuget rate limits and failed.

github-actions · 2023-10-09T06:42:13Z

Test Results

35 files ±0 119 suites ±0 1m 2s ⏱️ -7s
649 tests ±0 636 ✅ ±0 13 💤 ±0 0 ❌ ±0
665 runs ±0 645 ✅ ±0 20 💤 ±0 0 ❌ ±0

Results for commit 79e9960. ± Comparison against base commit 4c29726.

♻️ This comment has been updated with latest results.

codecov · 2023-10-09T06:42:31Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (4c29726) 63.00% compared to head (79e9960) 63.00%.

Additional details and impacted files

@@              Coverage Diff              @@
##           v8.0-preview     #582   +/-   ##
=============================================
  Coverage         63.00%   63.00%           
=============================================
  Files               244      244           
  Lines              5636     5636           
  Branches            369      369           
=============================================
  Hits               3551     3551           
  Misses             1978     1978           
  Partials            107      107

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

tomaszlaskowskiLC · 2023-10-15T14:51:44Z

docs/cqrs/authorization/index.md

@@ -0,0 +1,64 @@
+# Authorization
+
+Each command and query has to be authorized or must explicitly opt-out of authorization (it's enforced using Roslyn analyzers). You can specify which authorizer to use using the `AuthorizeWhen` attribute and custom `ICustomAuthorizer`. Opting-out is done using the `AllowUnauthorized` attribute. There is a predefined authorizer that uses role- and permission-based authorization. You can specify which permissions to enforce using `AuthorizeWhenHasAnyOf` and configure the role-to-permission relationship using `IRoleRegistrations`.


command, query and operation?
I wonder do we have a clear term for all three concepts. Sometimes commands and queries are jointly called CQRS operations, but this would be misleading in our case. 🤔

If we pick one, it should be used consistently in all contexts. I would prefer a separate term instead of enumerating "comands, queries and operations". Unfortunately, I don't have an idea, maybe someone else would fill in. 😄

We could adapt a bit the CQRS objects terminology. Maybe go back to the roots calling them RCQRS objects (Remote), however we have abandoned this terminology I'm afraid. Otherwise, we can get a little bit silly and call them CQRS+ objects, where + would mean the operation.

docs/cqrs/authorization/index.md

docs/cqrs/command/index.md

tomaszlaskowskiLC · 2023-10-15T16:09:20Z

docs/cqrs/operation/index.md

I really like starting with potential use cases!

tomaszlaskowskiLC · 2023-10-15T16:18:34Z

docs/cqrs/operation/index.md

+```csharp
+public class PayForAccessOH : IOperationHandler<PayForAccess, PaymentTokenDTO>
+{
+    private readonly IPaymentsService payments;


Ending service names with Service might be another topic for our freak fight weekly. 🤡

docs/cqrs/query/index.md

docs/external_integrations/messaging_masstransit/index.md

docs/cqrs/pipeline/avoid_commiting_transactions_in_handlers.md

docs/cqrs/query/index.md

docs/cqrs/validation/index.md

tomaszlaskowskiLC · 2023-11-16T11:28:58Z

docs/cqrs/validation/index.md

+
+> **Tip:** More on ids can be found [here](../../domain/id/index.md).
+
+If you need complex validation logic that needs to access external state, use `MustAsync`/`CustomAsync` validators. For `CustomAsync` validators, you can use `AddValidationError` helper to specify the error code.


It would be nice to add an example of async validation (checking for existence with dbContext should suffice).

It was there above this, moved this text above async validator to make it more clear.

docs/domain/domain_event/index.md

docs/external_integrations/authorization_ory_kratos/handling_webhooks.md

docs/domain/domain_event/index.md

Dragemil · 2023-11-30T15:47:13Z

docs/cqrs/authorization/index.md

@@ -0,0 +1,64 @@
+# Authorization
+
+Each command and query has to be authorized or must explicitly opt-out of authorization (it's enforced using Roslyn analyzers). You can specify which authorizer to use using the `AuthorizeWhen` attribute and custom `ICustomAuthorizer`. Opting-out is done using the `AllowUnauthorized` attribute. There is a predefined authorizer that uses role- and permission-based authorization. You can specify which permissions to enforce using `AuthorizeWhenHasAnyOf` and configure the role-to-permission relationship using `IRoleRegistrations`.


We could adapt a bit the CQRS objects terminology. Maybe go back to the roots calling them RCQRS objects (Remote), however we have abandoned this terminology I'm afraid. Otherwise, we can get a little bit silly and call them CQRS+ objects, where + would mean the operation.

Dragemil · 2023-11-30T15:50:03Z

docs/features/audit_logs/index.md

Do we want to also mention the features not present in this repo? Like LeanPipe, app rating and probably something else. We could have a list somewhere with just one sentence long descriptions and links to the docs (LeanPipe e.g. has some docs in its repo)

Yes, we could do it, but I can see that only app rating has public repo, leanpipe and notification center are private and I don't think that we should mention features that might not be available to user outside leancode.

Let's put that in the backlog - these repo will be open rather soon.

marcin-dardzinski · 2023-12-05T07:34:11Z

README.md

+</Project>
+```
+
+[/Directory.Build.props]: https://github.com/leancodepl/corelibrary/blob/v8.0-preview/Directory.Build.props


This will be broken very soon. I wonder if we can make it a link to a default branch no matter what it is.

We could point to the HEAD but we probably do not want docs just to point to newest commit. When v8 is released some other link also need to be updated. Will probably update it then.

marcin-dardzinski · 2023-12-05T07:36:58Z

docs/cqrs/authorization/index.md

@@ -0,0 +1,213 @@
+# Authorization
+
+Each command and query has to be authorized or must explicitly opt-out of authorization (it's enforced using Roslyn analyzers). You can specify which authorizer to use using the `AuthorizeWhen` attribute and custom `ICustomAuthorizer`. Opting-out is done using the `AllowUnauthorized` attribute. There is a predefined authorizer that uses role- and permission-based authorization. You can specify which permissions to enforce using `AuthorizeWhenHasAnyOf` and configure the role-to-permission relationship using `IRoleRegistrations`.


(it's enforced using Roslyn analyzers)

Do we have any entry in the docs covering this topic?

Not really, I will add this to backlog and reword it

docs/cqrs/authorization/index.md

docs/cqrs/pipeline/index.md

docs/cqrs/pipeline/adding_custom_middlewares.md

docs/domain/aggregate/index.md

marcin-dardzinski · 2023-12-05T08:31:56Z

docs/tests/faking_time/index.md

+
+    // Assert that the `DateCreated` time matches
+    // the expected time in UTC.
+    Assert.Equal(expectedTime.UtcDateTime, project.DateCreated);


Nit: FluentAssertions

Hm not sure about that, I think it should be as simple as possible and using FluentAssertions in docs might add some unnecessary complication (as it is not as popular and recognized XUnit's Assert).

docs/cqrs/pipeline/index.md

docs/quick_start/index.md

jakubfijalkowski · 2023-12-14T09:43:54Z

docs/README.md


-Our aim is to provide an opinionated framework for .NET Core app development. As for now we have, more-or-less, standardized:
+The LeanCode Core Library is a set of helper libraries developed at [our company](https://leancode.co/) that aids our day-to-day development. Not only does it serve as a facilitator in our day-to-day coding activities, but it also encapsulates comprehensive guidelines, gathers our collective knowledge on application architecture and development best practices.


Not now probably, but for future - we need to re-word this and put more focus on "CoreLib being a enterprise-ready framework that structures how you create the applications".

Sth like the second paragraph.

docs/quick_start/index.md

jakubfijalkowski · 2023-12-14T11:48:49Z

docs/quick_start/index.md

+
+After successfully setting up the local cluster, your next step is to initiate your application. Begin by navigating to the `backend` directory. This directory is the heart of your application, containing various subdirectories and files, each serving a specific purpose:
+
+```txt


This will change soon, so let's remember to fix it after the fact.

Sooner than I anticipated

jakubfijalkowski · 2023-12-14T11:53:53Z

docs/quick_start/index.md

+
+### Generating initial migrations
+
+Let's start with generating initial migrations. Begin by navigating, to the `backend/src/Apps/ProjectName.Migrations` directory. Generate initial migrations using the `dotnet ef` tool (install it via `dotnet tool install --global dotnet-ef`):


I talked with Krzysiek about this one, this tool IMO should be put in the dotnet-tools.json. /cc: @Saancreed

I will update this when it will be in dotnet-tools.json

jakubfijalkowski · 2023-12-14T11:55:02Z

docs/quick_start/index.md

+Then you can run the migrations and the API using the following command:
+
+```sh
+tilt up migrations api


This will run API only, it will not start migrations.

This is what we always had in README if I remember correctly it did start the migrations when I ran it. Anyway I separated those commands now.

docs/cqrs/index.md

jakubfijalkowski · 2023-12-14T12:08:30Z

docs/cqrs/index.md

+
+- **Separation of concerns:** CQRS enforces a clear separation of concerns between the write and read operations. This leads to a more maintainable and modular codebase, making it easier to understand, test, and develop.
+- **Improved security:** Security measures can be applied more granularly. For instance, you might have different authorization mechanisms for read and write operations, providing an additional layer of control.
+- **Validation on the write side:** With CQRS, the write side typically handles commands that change the state of the system. This is where validation of incoming data and business rules can be enforced. By centralizing validation logic on the write side, you ensure that all changes to the system go through a consistent validation process.


I don't get the typically here - what does it refer to?

And I don't get the point fully. Could you paraphrase it to me?

I think typically is unnecessary here and can be removed/

The point is that we do not need to include validation on our read side. I will reword it to make it more clear.

docs/cqrs/index.md

docs/cqrs/command/index.md

jakubfijalkowski · 2023-12-14T12:32:47Z

docs/cqrs/command/index.md

+
+## Naming conventions
+
+Commands in CQRS are responsible for modifying the state of the system, and therefore their names should reflect the action they trigger. A common convention is to use imperative verbs that clearly describe the intent, including the namespace as part of the contract, such as:


I don't get the including the namespace as part of the contract. What did you have in mind here?

This was @tomaszlaskowskiLC suggestion somewhere above. Namespace might sometimes provide additional information about the contract, and I think it should be treated as a part of it so that we do not create some weird folder structure which might confuse the clients.

docs/cqrs/command/index.md

docs/cqrs/query/index.md

…CommitTransaction middleware

wojtek2288 marked this pull request as draft October 9, 2023 06:35

wojtek2288 force-pushed the new-docs branch from 920fb52 to c45ab81 Compare October 9, 2023 06:42

wojtek2288 force-pushed the new-docs branch 7 times, most recently from 1c9f8c1 to 9291581 Compare October 11, 2023 06:53

tomaszlaskowskiLC reviewed Oct 15, 2023

View reviewed changes

wojtek2288 force-pushed the new-docs branch 2 times, most recently from 7219048 to 55c5858 Compare October 19, 2023 09:33

wojtek2288 commented Oct 19, 2023

View reviewed changes

docs/external_integrations/messaging_masstransit/index.md Outdated Show resolved Hide resolved

wojtek2288 force-pushed the new-docs branch 2 times, most recently from 8379cf2 to 3820958 Compare November 13, 2023 11:59

tomaszlaskowskiLC reviewed Nov 16, 2023

View reviewed changes

wojtek2288 force-pushed the new-docs branch 2 times, most recently from acdf7fe to a262605 Compare November 29, 2023 10:03

wojtek2288 marked this pull request as ready for review November 30, 2023 11:40

Saancreed reviewed Nov 30, 2023

View reviewed changes

Dragemil reviewed Nov 30, 2023

View reviewed changes

marcin-dardzinski reviewed Dec 5, 2023

View reviewed changes

marcin-dardzinski reviewed Dec 8, 2023

View reviewed changes

docs/cqrs/pipeline/index.md Outdated Show resolved Hide resolved

wojtek2288 force-pushed the new-docs branch from 0ae810e to 0c41e89 Compare December 13, 2023 13:42

wojtek2288 commented Dec 13, 2023

View reviewed changes

docs/quick_start/index.md Outdated Show resolved Hide resolved

jakubfijalkowski reviewed Dec 14, 2023

View reviewed changes

docs/cqrs/query/index.md Outdated Show resolved Hide resolved

docs/cqrs/query/index.md Outdated Show resolved Hide resolved

docs/cqrs/query/index.md Outdated Show resolved Hide resolved

Wojciech Klusek and others added 27 commits January 5, 2024 08:16

Extend [JsonConstructor] explanation

00a7e86

Highlight advice about commiting transactions, start with explaining …

ec96353

…CommitTransaction middleware

Add localization section

e93ccd7

Add overview

0048929

Use nuget logo in packages sections

9003d3b

Add TimeProvider sections

3fe2b90

Use colors similar to LeanCode branding

85f8f5c

Add open telemetry section

58b2320

Use previous General section as new github README

8f67098

Remove check links step as it exceeds nuget rate limit

52bdcea

Add favicon

9ec6030

Add kratos.yaml sample, api key explanation

06ad9de

Use Material admonitions across docs

0378f37

Pipeline refactor

c63d126

Add AuthorizeWhenHasAnyOf example

5741c5b

Remove unnecessary sentence

63a1b7e

Add quickstart, enable code copying

5c78292

Refactor quickstart

b136e04

Use 'data' instead of 'datasets'

6dcb625

Emphasize 'development' in template description

a201d0f

Rework template description, remove commands from dev-cluster setup

4efe6d1

Use new template structure, add links

333709c

Fix tests description in quickstart

40152cf

CQRS docs refactor v1

03f9a84

CQRS docs refactor v2

5d60470

Add projectname prefix to tilt, use dotnet tool restore in quickstart

daa917b

Rename Identifiable section to Entity

79e9960

wojtek2288 force-pushed the new-docs branch from 912f06a to 79e9960 Compare January 5, 2024 07:17

wojtek2288 merged commit 0e9010c into v8.0-preview Jan 5, 2024
10 checks passed

wojtek2288 deleted the new-docs branch January 5, 2024 07:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New docs #582

New docs #582

wojtek2288 commented Oct 9, 2023 •

edited

Loading

github-actions bot commented Oct 9, 2023 •

edited

Loading

codecov bot commented Oct 9, 2023 •

edited

Loading

tomaszlaskowskiLC Oct 15, 2023

Dragemil Nov 30, 2023 •

edited

Loading

tomaszlaskowskiLC Oct 15, 2023

tomaszlaskowskiLC Oct 15, 2023

tomaszlaskowskiLC Nov 16, 2023

wojtek2288 Nov 27, 2023

Dragemil Nov 30, 2023 •

edited

Loading

Dragemil Nov 30, 2023

wojtek2288 Dec 4, 2023

jakubfijalkowski Dec 4, 2023

marcin-dardzinski Dec 5, 2023

wojtek2288 Dec 6, 2023 •

edited

Loading

marcin-dardzinski Dec 5, 2023

wojtek2288 Dec 6, 2023

marcin-dardzinski Dec 5, 2023

wojtek2288 Dec 6, 2023

jakubfijalkowski Dec 14, 2023

jakubfijalkowski Dec 14, 2023

jakubfijalkowski Dec 14, 2023

jakubfijalkowski Dec 19, 2023

jakubfijalkowski Dec 14, 2023

wojtek2288 Dec 18, 2023

jakubfijalkowski Dec 14, 2023

wojtek2288 Dec 18, 2023

jakubfijalkowski Dec 14, 2023

jakubfijalkowski Dec 14, 2023

wojtek2288 Dec 20, 2023 •

edited

Loading

jakubfijalkowski Dec 14, 2023

wojtek2288 Dec 21, 2023

		@@ -0,0 +1,64 @@
		# Authorization

		Each command and query has to be authorized or must explicitly opt-out of authorization (it's enforced using Roslyn analyzers). You can specify which authorizer to use using the `AuthorizeWhen` attribute and custom `ICustomAuthorizer`. Opting-out is done using the `AllowUnauthorized` attribute. There is a predefined authorizer that uses role- and permission-based authorization. You can specify which permissions to enforce using `AuthorizeWhenHasAnyOf` and configure the role-to-permission relationship using `IRoleRegistrations`.


		> Tip: More on ids can be found [here](../../domain/id/index.md).

		If you need complex validation logic that needs to access external state, use `MustAsync`/`CustomAsync` validators. For `CustomAsync` validators, you can use `AddValidationError` helper to specify the error code.

		@@ -0,0 +1,213 @@
		# Authorization

		Each command and query has to be authorized or must explicitly opt-out of authorization (it's enforced using Roslyn analyzers). You can specify which authorizer to use using the `AuthorizeWhen` attribute and custom `ICustomAuthorizer`. Opting-out is done using the `AllowUnauthorized` attribute. There is a predefined authorizer that uses role- and permission-based authorization. You can specify which permissions to enforce using `AuthorizeWhenHasAnyOf` and configure the role-to-permission relationship using `IRoleRegistrations`.


		Our aim is to provide an opinionated framework for .NET Core app development. As for now we have, more-or-less, standardized:
		The LeanCode Core Library is a set of helper libraries developed at [our company](https://leancode.co/) that aids our day-to-day development. Not only does it serve as a facilitator in our day-to-day coding activities, but it also encapsulates comprehensive guidelines, gathers our collective knowledge on application architecture and development best practices.


		After successfully setting up the local cluster, your next step is to initiate your application. Begin by navigating to the `backend` directory. This directory is the heart of your application, containing various subdirectories and files, each serving a specific purpose:

		```txt


		### Generating initial migrations

		Let's start with generating initial migrations. Begin by navigating, to the `backend/src/Apps/ProjectName.Migrations` directory. Generate initial migrations using the `dotnet ef` tool (install it via `dotnet tool install --global dotnet-ef`):


		## Naming conventions

		Commands in CQRS are responsible for modifying the state of the system, and therefore their names should reflect the action they trigger. A common convention is to use imperative verbs that clearly describe the intent, including the namespace as part of the contract, such as:

New docs #582

New docs #582

Conversation

wojtek2288 commented Oct 9, 2023 • edited Loading

github-actions bot commented Oct 9, 2023 • edited Loading

Test Results

codecov bot commented Oct 9, 2023 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Dragemil Nov 30, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Dragemil Nov 30, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wojtek2288 Dec 6, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wojtek2288 Dec 20, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wojtek2288 commented Oct 9, 2023 •

edited

Loading

github-actions bot commented Oct 9, 2023 •

edited

Loading

codecov bot commented Oct 9, 2023 •

edited

Loading

Dragemil Nov 30, 2023 •

edited

Loading

Dragemil Nov 30, 2023 •

edited

Loading

wojtek2288 Dec 6, 2023 •

edited

Loading

wojtek2288 Dec 20, 2023 •

edited

Loading