Prepare v5.17.0.

Author: mclift

CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## 5.17.0 - 2024.12.30
+### Changed
+ - Use `PackageLicenseExpression` in csproj file [#583], [#584]
+### Added
+ - Added mermaid graph support [#585]
+ - Allow PermitDynamic destination state to be calculated with an async function (Task) [#595]
+ - Updated readme to clarify re-entry behaviour of dynamic transitions [#604]
+ - Added .NET 9.0 to build targets [#610]
+### Fixed
+ - Unexpected graph labels for internal transitions [#587]
+ - Labels not escaped in `UmlDotGraphStyle` [#597]
+
 ## 5.16.0 - 2024.05.24
 ### Changed
  - Permit state reentry from dynamic transitions [#565]
@@ -222,6 +234,14 @@ Version 5.10.0 is now listed as the newest, since it has the highest version num
 ### Removed
 ### Fixed
 
+[#610]: https://github.com/dotnet-state-machine/stateless/pull/610
+[#604]: https://github.com/dotnet-state-machine/stateless/issues/604
+[#597]: https://github.com/dotnet-state-machine/stateless/pull/597
+[#595]: https://github.com/dotnet-state-machine/stateless/pull/595
+[#587]: https://github.com/dotnet-state-machine/stateless/pull/589
+[#585]: https://github.com/dotnet-state-machine/stateless/issues/585
+[#584]: https://github.com/dotnet-state-machine/stateless/pull/584
+[#583]: https://github.com/dotnet-state-machine/stateless/pull/583
 [#575]: https://github.com/dotnet-state-machine/stateless/pull/575
 [#574]: https://github.com/dotnet-state-machine/stateless/pull/574
 [#570]: https://github.com/dotnet-state-machine/stateless/pull/570

README.md

@@ -144,7 +144,7 @@ Trigger parameters can be used to dynamically select the destination state using
 
 ### Ignored Transitions and Reentrant States
 
-Firing a trigger that does not have an allowed transition associated with it will cause an exception to be thrown.
+In Stateless, firing a trigger that does not have an allowed transition associated with it will cause an exception to be thrown. This ensures that all transitions are explicitly defined, preventing unintended state changes.
 
 To ignore triggers within certain states, use the `Ignore(TTrigger)` directive:
 
@@ -153,7 +153,7 @@ phoneCall.Configure(State.Connected)
     .Ignore(Trigger.CallDialled);
 ```
 
-Alternatively, a state can be marked reentrant so its entry and exit actions will fire even when transitioning from/to itself:
+Alternatively, a state can be marked reentrant. A reentrant state is one that can transition back into itself. In such cases, the state's exit and entry actions will be executed, providing a way to handle events that require the state to reset or reinitialize.
 
 ```csharp
 stateMachine.Configure(State.Assigned)
@@ -167,6 +167,23 @@ By default, triggers must be ignored explicitly. To override Stateless's default
 stateMachine.OnUnhandledTrigger((state, trigger) => { });
 ```
 
+### Dynamic State Transitions and State Re-entry
+
+Dynamic state transitions allow the destination state to be determined at runtime based on trigger parameters or other logic.
+
+```csharp
+stateMachine.Configure(State.Start)
+    .PermitDynamic(Trigger.CheckScore, () => score < 10 ? State.LowScore : State.HighScore);
+```
+
+When a dynamic transition results in the same state as the current state, it effectively becomes a reentrant transition, causing the state's exit and entry actions to execute. This can be useful for scenarios where the state needs to refresh or reset based on certain triggers.
+
+```csharp
+stateMachine.Configure(State.Waiting)
+    .OnEntry(() => Console.WriteLine($"Elapsed time: {elapsed} seconds..."))
+    .PermitDynamic(Trigger.CheckStatus, () => ready ? State.Done : State.Waiting);
+```
+
 ### State change notifications (events)
 
 Stateless supports 2 types of state machine events:
@@ -183,7 +200,7 @@ This event will be invoked every time the state machine changes state.
 ```csharp
 stateMachine.OnTransitionCompleted((transition) => { });
 ```
-This event will be invoked at the very end of the trigger handling, after the last  entry action has been executed.
+This event will be invoked at the very end of the trigger handling, after the last entry action has been executed.
 
 ### Export to DOT graph
 
@@ -207,9 +224,9 @@ digraph {
 This can then be rendered by tools that support the DOT graph language, such as the [dot command line tool](http://www.graphviz.org/doc/info/command.html) from [graphviz.org](http://www.graphviz.org) or [viz.js](https://github.com/mdaines/viz.js). See http://www.webgraphviz.com for instant gratification.
 Command line example: `dot -T pdf -o phoneCall.pdf phoneCall.dot` to generate a PDF file.
 
-### Export to mermaid graph
+### Export to Mermaid graph
 
-It can be useful to visualize state machines on runtime. With this approach the code is the authoritative source and state diagrams are by-products which are always up to date.
+Mermaid graphs can also be generated from state machines.
 
 ```csharp
 phoneCall.Configure(State.OffHook)
@@ -226,7 +243,7 @@ stateDiagram-v2
     OffHook --> Ringing : CallDialled
 ```
 
-This can then be rendered by GitHub or [Obsidian](https://github.com/obsidianmd)
+This can be rendered by GitHub markdown or an engine such as [Obsidian](https://github.com/obsidianmd).
 
 ``` mermaid
 stateDiagram-v2

src/Stateless/Stateless.csproj

@@ -8,7 +8,7 @@
     <Description>Create state machines and lightweight state machine-based workflows directly in .NET code</Description>
     <Copyright>Copyright © Stateless Contributors 2009-$([System.DateTime]::Now.ToString(yyyy))</Copyright>
     <NeutralLanguage>en-US</NeutralLanguage>
-    <VersionPrefix>5.16.0</VersionPrefix>
+    <VersionPrefix>5.17.0</VersionPrefix>
     <Authors>Stateless Contributors</Authors>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>

src/Stateless/docs/README.md

@@ -41,7 +41,7 @@ Some useful extensions are also provided:
  * Ability to store state externally (for example, in a property tracked by an ORM)
  * Parameterised triggers
  * Reentrant states
- * Export to DOT graph
+ * Export to DOT and Mermaid graph
 
 ## Documentation