From c71b4115dfba537da70937c878b93b5049c6e031 Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Tue, 17 Feb 2026 20:00:22 +0100 Subject: [PATCH 1/6] Use the semantic colored `` elements --- docs/_preview/go.mod | 2 +- docs/_preview/go.sum | 4 +- docs/content/docs/guides/start-new-project.md | 14 +++--- docs/content/docs/introduction/_index.md | 8 +-- docs/content/docs/introduction/concepts.md | 10 ++-- .../docs/introduction/naming-conventions.md | 18 +++---- docs/content/docs/quick-start/_index.md | 49 ++++++++++--------- 7 files changed, 54 insertions(+), 51 deletions(-) diff --git a/docs/_preview/go.mod b/docs/_preview/go.mod index 0787e19..f444906 100644 --- a/docs/_preview/go.mod +++ b/docs/_preview/go.mod @@ -3,7 +3,7 @@ module github.com/SpineEventEngine/documentation/docs/_preview go 1.22.0 require ( - github.com/SpineEventEngine/site-commons v0.0.0-20260213171221-c1157022c545 // indirect + github.com/SpineEventEngine/site-commons v0.0.0-20260217160941-2a1a87ca8cfb // indirect github.com/SpineEventEngine/validation/docs v0.0.0-20260205202311-181ba8844107 // indirect github.com/gohugoio/hugo-mod-bootstrap-scss/v5 v5.20300.20400 // indirect github.com/gohugoio/hugo-mod-jslibs-dist/popperjs/v2 v2.21100.20000 // indirect diff --git a/docs/_preview/go.sum b/docs/_preview/go.sum index 561c7cb..107f6f3 100644 --- a/docs/_preview/go.sum +++ b/docs/_preview/go.sum @@ -1,5 +1,5 @@ -github.com/SpineEventEngine/site-commons v0.0.0-20260213171221-c1157022c545 h1:NI8WYIfw5yv/FXNhxG2zgiU3J0YChheRQugosxkopoc= -github.com/SpineEventEngine/site-commons v0.0.0-20260213171221-c1157022c545/go.mod h1:tkAl4StIREKmz9r5PiJtuDhvwMMkFXKWcaTyxhIikho= +github.com/SpineEventEngine/site-commons v0.0.0-20260217160941-2a1a87ca8cfb h1:4OsCLSX35TznTy8qs/l8HkFUYKNPfMF/tgO1iYe9LfI= +github.com/SpineEventEngine/site-commons v0.0.0-20260217160941-2a1a87ca8cfb/go.mod h1:tkAl4StIREKmz9r5PiJtuDhvwMMkFXKWcaTyxhIikho= github.com/SpineEventEngine/validation/docs v0.0.0-20260205202311-181ba8844107 h1:2DHRIwwLudP6l3Kh7Nd4KR4uXcsDtIAXE9adW68ivME= github.com/SpineEventEngine/validation/docs v0.0.0-20260205202311-181ba8844107/go.mod h1:STHyjXejVvPmfrxujfDvhofmjg55mMk+fwI3TVL0b4Y= github.com/gohugoio/hugo-mod-bootstrap-scss/v5 v5.20300.20400 h1:L6+F22i76xmeWWwrtijAhUbf3BiRLmpO5j34bgl1ggU= diff --git a/docs/content/docs/guides/start-new-project.md b/docs/content/docs/guides/start-new-project.md index 18a5868..664f868 100755 --- a/docs/content/docs/guides/start-new-project.md +++ b/docs/content/docs/guides/start-new-project.md @@ -148,7 +148,7 @@ and polish the code of this important development step. ### Events When the IDs are defined it’s time to define [event][event-concept] messages. The events are named -as facts formulated as past participles, e.g. `RepositoryRegistered` or `TaskCreated`. +as facts formulated as past participles, e.g. {{< code "event" "RepositoryRegistered" >}} or {{< code "event" "TaskCreated" >}}. They are defined in files with the [`_events.proto`][events-proto] suffix (e.g. `order_events.proto`, `customer_events.proto`). If your context is small it can be just `events.proto`. @@ -158,8 +158,8 @@ Create a Pull Request with the event definitions when they are ready. Similar to events, [command][command-concept] messages are defined in files having the names ending with the [`_commands.proto`][commands-proto] suffix (or just `commands.proto` for a small context). -Commands are defined as imperative in a form of “do something”, e.g. `RegisterRepository` -or `CreateTask`. +Commands are defined as imperative in a form of “do something”, e.g. {{< code "command" "RegisterRepository" >}} +or {{< code "command" "CreateTask" >}}. Finalize defining commands with a Pull Request. @@ -189,8 +189,8 @@ The [entity state][entity-state-naming] is a holder of the entity data. It does a whole [entity][entity-concept] but depicts the shape of its data. The definitions of entity states are [gathered][entity-state-proto] in a file named after -a business model thing. E.g. for a `Task` aggregate, the definitions would be defined in -a `task.proto` file. +a business model thing. E.g. for a {{< code "aggregate" "Task" >}} aggregate, the definitions +would be defined in a `task.proto` file. As with the other steps, create a Pull Request to review the entity states with the team. @@ -208,7 +208,7 @@ the business logic the same way it works in the application. All the code must conform to your standards of the code and documentation quality and be tested thoroughly. -When a backend for the scenario is done a new PR is created and reviewed. +When a backend for the scenario is done a new PR is created and reviewed. ### Fulfilling the vertical @@ -221,7 +221,7 @@ with the previous one. As noted, the scope of this iteration is to prepare the front-facing part for the scenario: either a UI if one is needed, or the public API, or a dedicated idiomatic client. -As soon as the implementation is ready, another PR and review come along. +As soon as the implementation is ready, another PR and review come along. ## Start over again diff --git a/docs/content/docs/introduction/_index.md b/docs/content/docs/introduction/_index.md index 493befd..a38ad84 100644 --- a/docs/content/docs/introduction/_index.md +++ b/docs/content/docs/introduction/_index.md @@ -150,11 +150,11 @@ final class TaskItemProjection #### Repositories The framework provides default implementations for repositories. A custom `Repository` class may be needed for: - * Dispatching messages to entities in a non-standard way. + * **Dispatching messages to entities in a non-standard way**. By default, a command is dispatched using the first field of the command message as an ID of the target entity. An event is dispatched by the ID of the entity which emitted the event. - * Domain-specific operations on entities of this kind. + * **Domain-specific operations** on entities of this kind. Repositories are added to the Bounded Context they belong when it is created: @@ -170,8 +170,8 @@ This wires repositories into the message delivery mechanism of the corresponding #### Testing Implementation of the Bounded Context is tested using the messaging paradigm. -The following code snippet asserts that handling a command `CreateTask` produces one -`TaskCreated` event with expected arguments. +The following code snippet asserts that handling a command {{< code "command" "CreateTask" >}} +produces one {{< code "event" "TaskCreated" >}} event with expected arguments. ```java // Given diff --git a/docs/content/docs/introduction/concepts.md b/docs/content/docs/introduction/concepts.md index 1b5ae86..cffde82 100755 --- a/docs/content/docs/introduction/concepts.md +++ b/docs/content/docs/introduction/concepts.md @@ -40,9 +40,9 @@ regular events. If an event is a fact of something that happened to a domain mod a fact that states the reason why a command was not handled. Consider the following examples of rejections: -* `CreditCardValidationDeclined`, -* `OrderCannotBeEmpty`, -* `InsufficientFunds`. +* {{< code "rejection" "CreditCardValidationDeclined" >}}, +* {{< code "rejection" "OrderCannotBeEmpty" >}}, +* {{< code "rejection" "InsufficientFunds" >}}. In Spine, rejections are defined as Protobuf messages in the file which names ends with `rejections.proto`. @@ -85,8 +85,8 @@ final class TaskAggregate Event Subscriber is an object which subscribes to receive events. -The example below shows how a [Projection](#projection) class subscribed to the `TaskCompleted` -event. +The example below shows how a [Projection](#projection) class subscribed +to the {{< code "event" "TaskCompleted" >}} event. ```java final class TaskProjection diff --git a/docs/content/docs/introduction/naming-conventions.md b/docs/content/docs/introduction/naming-conventions.md index ed3b5ed..985b4b2 100755 --- a/docs/content/docs/introduction/naming-conventions.md +++ b/docs/content/docs/introduction/naming-conventions.md @@ -222,26 +222,26 @@ message CreateTask { A command is defined as an imperative: - * `CreateProject` - * `AssignTask` - * `RemoveComment` + * {{< code "command" "CreateProject" >}} + * {{< code "command" "AssignTask" >}} + * {{< code "command" "RemoveComment" >}} ### Events Events are named as facts formulated as past participles, for example: - * `ProjectCreated` - * `TaskAssigned` - * `CommentRemoved` + * {{< code "event" "ProjectCreated" >}} + * {{< code "event" "TaskAssigned" >}} + * {{< code "event" "CommentRemoved" >}} ### Rejections A rejection is named after a reason of why a command cannot be handled. In fact, rejection notifies on a state of the domain model, for example: - * `TaskAlreadyExists` - * `InsufficientFunds` - * `ProjectAlreadyCompleted` + * {{< code "rejection" "TaskAlreadyExists" >}} + * {{< code "rejection" "InsufficientFunds" >}} + * {{< code "rejection" "ProjectAlreadyCompleted" >}} ### Entity states diff --git a/docs/content/docs/quick-start/_index.md b/docs/content/docs/quick-start/_index.md index 4ac8ee2..9216889 100755 --- a/docs/content/docs/quick-start/_index.md +++ b/docs/content/docs/quick-start/_index.md @@ -193,7 +193,7 @@ Now, let's look into the data structure of the Hello context. The data types of the Hello context are defined under the `src/main/proto/hello` directory with the following files: - * **`commands.proto`** — this file defines the `Print` command. + * **`commands.proto`** — this file defines the {{< code "command" "Print" >}} command. {{% note-block class="note" %}} By convention, commands are defined in a file with the `commands` suffix @@ -201,15 +201,16 @@ in its name. It can be, for example, `order_commands.proto` or just `commands.pr like in our example. {{% /note-block %}} - * **`events.proto`** — this file defines the `Printed` event. + * **`events.proto`** — this file defines the {{< code "event" "Printed" >}} event. {{% note-block class="note" %}} Similarly to commands, events are defined in proto files having the `events` suffix in their names. {{% /note-block %}} -These two files define signals used by the Hello context. There's also data of the `Console` -Process Manager, which is defined in the package **`server`** in the file **`console.proto`**. +These two files define signals used by the Hello context. There's also data of the +{{< code "process-manager" "Console" >}} Process Manager, which is defined in the +package **`server`** in the file **`console.proto`**. {{% note-block class="note" %}} We arrange the sub-package `server` to highlight the fact that this is server-only data. It is not @@ -237,7 +238,7 @@ required for all proto files of a Spine-based project. import "spine/options.proto"; ``` -The following file-wide option defines the prefix for type names used in this file. +The following file-wide option defines the prefix for type names used in this file. }} command: }}. The following code obtains the name of the user, and the text to print from the received command, and then applies them to the state of the Process Manager. Instances of the `Console` class store @@ -615,9 +616,10 @@ protected BoundedContextBuilder contextBuilder() { return HelloContext.newBuilder(); } ``` -Now we can get down to the tests. The suite verifiers the outcome of the `Print` command. -The test methods are gathered under the nested class called -`PrintCommand`. The class holds the reference to the command as its field: +Now we can get down to the tests. The suite verifiers the outcome of the +{{< code "command" "Print" >}} command. The test methods are gathered under +the nested class called `PrintCommand`. The class holds the reference to the +command as its field: }} command. ### Sending the command @@ -847,9 +849,9 @@ public void sendCommand() { The method does three things: 1. Creates a command message using the login name of the current computer user. - 2. Subscribes to the `Printed` event which will be generated as the result of - handling the command we are going to post (and only this instance of the command, - not all `Print` commands). + 2. Subscribes to the {{< code "event" "Printed" >}} event which will be generated + as the result of handling the command we are going to post (and only this instance + of the command, not all {{< code "command" "Print" >}} commands). 3. Posts the command. Let's review subscribing and posting in details. @@ -860,18 +862,18 @@ most of the commands using `client.onBehalfOf(UserId)`. The `command(commandMessage)` call tells we want to send a command with the passed message. -Then, we subscribe to the `Printed` event which would be generated as the result of handling -the command. The events obtained from the server would be passed to the `onPrinted()` method -of the `Client` class. +Then, we subscribe to the {{< code "event" "Printed" >}} event which would be +generated as the result of handling the command. The events obtained from the +server would be passed to the `onPrinted()` method of the `Client` class. The `post()` method sends the command to the server, returning the set with one `Subscription` -to the `Printed` event. We store the returned set in the field to use later for cancelling -the subscription. +to the {{< code "event" "Printed" >}} event. We store the returned set in the field +to use later for cancelling the subscription. ### Handling the event -When the client code receives the `Printed` event, it prints its data and then -cancels the subscription: +When the client code receives the {{< code "event" "Printed" >}} event, it prints +its data and then cancels the subscription: }}, {{< code "process-manager" "ProcessManager" >}}, +or {{< code "projection" "Projection" >}}. Then, these entity types are assembled into a Bounded Context and tested as a whole. A test suite sends signals (i.e. commands or events) to the implementation of the Bounded Context From 36c5d37c0b013d8e84498161f137c15680b1847b Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Wed, 18 Feb 2026 15:35:03 +0100 Subject: [PATCH 2/6] Use the semantic code tags --- docs/content/docs/examples/_index.md | 2 +- docs/content/docs/guides/integration.md | 2 +- docs/content/docs/guides/validation.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/content/docs/examples/_index.md b/docs/content/docs/examples/_index.md index c8cee6b..137fd39 100755 --- a/docs/content/docs/examples/_index.md +++ b/docs/content/docs/examples/_index.md @@ -31,4 +31,4 @@ Please see the selected list of the examples with the descriptions below. - [Simple HTML/JS To-Do List client]({{% get-site-data "repositories.examples" %}}/todo-list/tree/master/client/html-js/) — a client app with very basic features. - [To-Do List client on Angular]({{% get-site-data "repositories.examples" %}}/todo-list/tree/master/client/angular/) - — a more featured client built with Angular 10. + — a more featured client built with Angular 10. diff --git a/docs/content/docs/guides/integration.md b/docs/content/docs/guides/integration.md index 0e90a31..6ba3312 100755 --- a/docs/content/docs/guides/integration.md +++ b/docs/content/docs/guides/integration.md @@ -328,7 +328,7 @@ private void emitIfStatusKnown(TsaPassenger tsaPassenger) { } ``` The [Process Manager]({{% get-site-data "repositories.examples" %}}/airport/blob/master/takeoffs-and-landings/src/main/java/io/spine/example/airport/tl/passengers/BoardingProcman.java) -accumulates the Events and, once the whole *Flight* is boarded, emits a `BoardingComplete` event, +accumulates the Events and, once the whole *Flight* is boarded, emits a {{< code "event" "BoardingComplete" >}} event, which is later consumed by the [*Flight* Aggregate]({{% get-site-data "repositories.examples" %}}/airport/blob/master/takeoffs-and-landings/src/main/java/io/spine/example/airport/tl/FlightAggregate.java). advanced feature of Protobuf, +options work. Those who are interested in the details of this _advanced feature_ of Protobuf, please see the [Protobuf Guide](https://developers.google.com/protocol-buffers/docs/proto3#custom_options) for details. {{% /note-block %}} From 2bb7c7d91a183bf67e3fb19733fe7614b1063fcd Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Wed, 18 Feb 2026 15:35:55 +0100 Subject: [PATCH 3/6] Fix typo --- docs/content/docs/examples/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/docs/examples/_index.md b/docs/content/docs/examples/_index.md index 137fd39..5ae83fd 100755 --- a/docs/content/docs/examples/_index.md +++ b/docs/content/docs/examples/_index.md @@ -19,7 +19,7 @@ Please see the selected list of the examples with the descriptions below. - [Kanban]({{% get-site-data "repositories.examples" %}}/kanban/) — shows orchestrating Aggregates using Process Managers. - [Airport]({{% get-site-data "repositories.examples" %}}/airport/) — integrating - a third-party systems using a Bounded Context. This example accompanies + a third-party system using a Bounded Context. This example accompanies the [“Integration with a Third Party”](docs/guides/integration/) guide. - [To-Do List]({{% get-site-data "repositories.examples" %}}/todo-list/) — a simple task management system with multiple client applications. From 0d71cb9ce51f503b3b871124a0f658e8aef3a50d Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Wed, 18 Feb 2026 15:50:47 +0100 Subject: [PATCH 4/6] Use semantic code tags --- docs/content/docs/guides/validation.md | 4 +-- .../docs/introduction/naming-conventions.md | 8 +++--- docs/content/docs/quick-start/_index.md | 28 +++++++++---------- 3 files changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/content/docs/guides/validation.md b/docs/content/docs/guides/validation.md index 62e311c..006c28d 100755 --- a/docs/content/docs/guides/validation.md +++ b/docs/content/docs/guides/validation.md @@ -318,8 +318,8 @@ therefore it is implicitly required. By default, the framework will use it in co as an identifier of the entity handling this command. This convention does not apply to [Events](docs/introduction/naming-conventions#eventsproto). -Unlike Commands, event routing is typically specific to the use case. For example, `UserView` projection -may require a user ID to handle events, whereas the `ProfilePictureGallery` projection might use +Unlike Commands, event routing is typically specific to the use case. For example, {{< code "projection" "UserView" >}} projection +may require a user ID to handle events, whereas the {{< code "projection" "ProfilePictureGallery" >}} projection might use a different routing approach, such as grouping by a user group or an email domain associated with a user. Therefore, all Event fields are not required by default. diff --git a/docs/content/docs/introduction/naming-conventions.md b/docs/content/docs/introduction/naming-conventions.md index 985b4b2..82fdc7c 100755 --- a/docs/content/docs/introduction/naming-conventions.md +++ b/docs/content/docs/introduction/naming-conventions.md @@ -91,10 +91,10 @@ an event, and it is likely there are conditions under which a command cannot be ### Entity states We recommend gathering definition of related entity states in a file named after a business model -thing. Suppose we have a `Task` aggregate, `TaskItem` and `TaskDetails` projections, and -a Process Manager which is responsible for movement of a task from one project to another, there -would be `task.proto` file, with all Task-related data types definitions. A project-related data -types would be defined in a `project.proto` file. +thing. Suppose we have a {{< code "aggregate" "Task" >}} aggregate, {{< code "projection" "TaskItem" >}} +and {{< code "projection" "TaskDetails" >}} projections, and a Process Manager which is responsible for +movement of a task from one project to another, there would be `task.proto` file, with all Task-related +data types definitions. The project-related data types would be defined in a `project.proto` file. As it was already mentioned, `TaskId` and `ProjectId` are defined in the `identifiers.proto` file, and `task.proto` and `project.proto` import this file. diff --git a/docs/content/docs/quick-start/_index.md b/docs/content/docs/quick-start/_index.md index 9216889..d0a1f0f 100755 --- a/docs/content/docs/quick-start/_index.md +++ b/docs/content/docs/quick-start/_index.md @@ -15,7 +15,7 @@ it won't take long. ## What we'll do We'll go through the example which shows a Bounded Context called “Hello”. -The context has one `ProcessManager`, which handles the `Print` command +The context has one `ProcessManager`, which handles the {{< code "command" "Print" >}} command sent from the client-side code to the server-side code hosting the context. We'll go through the production code of the example suite, and through the code which tests the Hello context. @@ -65,12 +65,11 @@ The first line tells which Gradle task we run. The following couple of lines is logging that informs us that the server was started. The line with the `Environment` tells that we're running the application in the `Production` -environment. -The line with “Hello World!” text is the “meat” of this example suite. -It is what our `ProcessManager` (called `Console`) does in response to the `Print` command received -from the `Client`. -The text in between brackets is the name of the current computer user. The name was passed as -the argument of the `Print` command. +environment. The line with “Hello World!” text is the “meat” of this example suite. +It is what our `ProcessManager` (called `Console`) does in response to the +{{< code "command" "Print" >}} command received from the `Client`. The text +in between brackets is the name of the current computer user. The name was passed +as the argument of the {{< code "command" "Print" >}} command. {{% note-block class="note" %}} We opted to show a `ProcessManager` — instead of an `Aggregate` — because @@ -79,8 +78,8 @@ that is the job of Process Managers. We also want to highlight the importance of this architectural pattern. {{% /note-block %}} -The output that follows is the logging produced by the `Client` class as it receives the `Printed` -event from the server. +The output that follows is the logging produced by the `Client` class as it receives the +{{< code "event" "Printed" >}} event from the server. Then, the server shuts down concluding the example. @@ -433,7 +432,7 @@ final class Console extends ProcessManager { The generic arguments passed to `ProcessManager` are: 1. `String` — the type of the ID of the entity. Remember the type -of the first field of the `Print` command? + of the first field of the {{< code "command" "Print" >}} command? 2. `Output` — the type of the entity state, which we reviewed in the previous section. @@ -523,8 +522,8 @@ After the event is generated, it is posted to the `EventBus` and delivered to subscribers automatically. You don't need to write any code for this. {{% /note-block %}} -Now, let's see how the `Console` Process Manager is exposed to the outer world so that it can -receive commands. +Now, let's see how the {{< code "process-manager" "Console" >}} Process Manager +is exposed to the outer world so that it can receive commands. ## Assembling the Hello context @@ -679,8 +678,9 @@ void event() { ### Testing entity state update -For testing the state of the `Console` Process Manager was updated, we construct the expected -state and pass it to the `assertState()` method of the test fixture: +For testing the state of the {{< code "process-manager" "Console" >}} Process Manager +was updated, we construct the expected state and pass it to the `assertState()` +method of the test fixture: Date: Wed, 18 Feb 2026 15:56:54 +0100 Subject: [PATCH 5/6] Clean up --- docs/content/docs/guides/start-new-project.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/docs/guides/start-new-project.md b/docs/content/docs/guides/start-new-project.md index 664f868..e06dd5f 100755 --- a/docs/content/docs/guides/start-new-project.md +++ b/docs/content/docs/guides/start-new-project.md @@ -158,8 +158,8 @@ Create a Pull Request with the event definitions when they are ready. Similar to events, [command][command-concept] messages are defined in files having the names ending with the [`_commands.proto`][commands-proto] suffix (or just `commands.proto` for a small context). -Commands are defined as imperative in a form of “do something”, e.g. {{< code "command" "RegisterRepository" >}} -or {{< code "command" "CreateTask" >}}. +Commands are defined as imperative in a form of “do something”, e.g. +{{< code "command" "RegisterRepository" >}} or {{< code "command" "CreateTask" >}}. Finalize defining commands with a Pull Request. From 09477dde2b94e0e673205165e23d0cfa54587b42 Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Wed, 18 Feb 2026 16:02:38 +0100 Subject: [PATCH 6/6] Clean up --- docs/content/docs/quick-start/_index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/content/docs/quick-start/_index.md b/docs/content/docs/quick-start/_index.md index d0a1f0f..ac637b4 100755 --- a/docs/content/docs/quick-start/_index.md +++ b/docs/content/docs/quick-start/_index.md @@ -1003,8 +1003,7 @@ using Protobuf. Using these `.proto` files Spine Model Compiler generates the co the defined data types. After that, we add the business logic for handling commands or events in entity classes derived from -{{< code "aggregate" "Aggregate" >}}, {{< code "process-manager" "ProcessManager" >}}, -or {{< code "projection" "Projection" >}}. +`Aggregate`, `ProcessManager`, or `Projection`. Then, these entity types are assembled into a Bounded Context and tested as a whole. A test suite sends signals (i.e. commands or events) to the implementation of the Bounded Context