com.wallstop-studios.dxmessaging 2.1.3 → 2.1.5

package/.llm/skills/documentation/changelog-management.md

@@ -0,0 +1,190 @@
+---
+title: "Changelog Management"
+id: "changelog-management"
+category: "documentation"
+version: "1.0.0"
+created: "2026-01-22"
+updated: "2026-01-22"
+
+source:
+  repository: "wallstop/DxMessaging"
+  files:
+    - path: "CHANGELOG.md"
+    - path: "package.json"
+  url: "https://github.com/wallstop/DxMessaging"
+
+tags:
+  - "changelog"
+  - "documentation"
+  - "versioning"
+  - "semantic-versioning"
+  - "release-notes"
+  - "keep-a-changelog"
+  - "user-communication"
+
+complexity:
+  level: "basic"
+  reasoning: "Follows a standard format (Keep a Changelog) with clear rules for entry classification"
+
+impact:
+  performance:
+    rating: "none"
+    details: "Documentation only, no runtime impact"
+  maintainability:
+    rating: "high"
+    details: "Well-maintained changelogs dramatically improve project maintainability and reduce support burden"
+  testability:
+    rating: "none"
+    details: "Documentation does not affect testability"
+
+prerequisites:
+  - "Basic understanding of semantic versioning"
+  - "Understanding of what constitutes a user-facing change"
+
+dependencies:
+  packages: []
+  skills:
+    - "documentation-updates"
+
+applies_to:
+  languages:
+    - "C#"
+    - "Markdown"
+  frameworks:
+    - "Unity"
+    - ".NET"
+  versions:
+    unity: ">=2021.3"
+    dotnet: ">=netstandard2.0"
+
+aliases:
+  - "Release notes"
+  - "Version history"
+  - "Change log"
+
+related:
+  - "documentation-updates"
+  - "changelog-entry-writing"
+  - "changelog-release-workflow"
+
+status: "stable"
+---
+
+# Changelog Management
+
+> **One-line summary**: Maintain a human-readable, chronologically organized record of notable changes following the Keep a Changelog format.
+
+## Overview
+
+A changelog is a curated, chronological record of user-facing changes for each release. It helps users understand what changed, whether a version is safe to adopt, and how to plan upgrades without digging through commits.
+
+In a Unity messaging library context, the changelog is the primary source of truth for:
+
+- New features that users can adopt
+- Breaking changes to watch for
+- Fixes that resolve user-visible bugs
+- Performance changes that affect runtime behavior
+
+## Problem Statement
+
+Without a well-maintained changelog:
+
+- Users cannot tell what changed between versions
+- Breaking changes surprise users after upgrading
+- Support burden increases as users ask "what's new?"
+- Historical context for decisions is lost
+
+## Solution
+
+### Core Concept: Keep a Changelog Format
+
+Follow the [Keep a Changelog](https://keepachangelog.com/) specification. Every release section uses these categories:
+
+| Category       | Description                       | Example                                    |
+| -------------- | --------------------------------- | ------------------------------------------ |
+| **Added**      | New features                      | New message type, new API method           |
+| **Changed**    | Changes to existing functionality | Modified method signature, behavior change |
+| **Deprecated** | Features to be removed in future  | Old API marked for removal                 |
+| **Removed**    | Features removed in this release  | Deleted obsolete classes                   |
+| **Fixed**      | Bug fixes                         | Corrected message routing issue            |
+| **Security**   | Vulnerability patches             | Fixed message validation exploit           |
+
+### File Structure
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- New feature being developed
+
+## [2.1.4] - 2026-01-15
+
+### Fixed
+
+- Resolved issue with targeted message delivery when target is destroyed
+
+[Unreleased]: https://github.com/wallstop/DxMessaging/compare/v2.1.4...HEAD
+```
+
+### When to Update the Changelog
+
+Update the changelog for **every user-facing change**:
+
+| Change Type                          | Update Changelog? | Category                   |
+| ------------------------------------ | ----------------- | -------------------------- |
+| New public API                       | Yes               | Added                      |
+| Bug fix                              | Yes               | Fixed                      |
+| Performance improvement              | Yes               | Changed                    |
+| Internal refactoring (no API change) | No                | N/A                        |
+| Test additions                       | No                | N/A                        |
+| Documentation fixes                  | Maybe             | Changed (if significant)   |
+| Dependency updates                   | Maybe             | Changed (if affects users) |
+| Breaking changes                     | Yes               | Changed/Removed            |
+
+### Semantic Versioning Guidelines
+
+Given version `MAJOR.MINOR.PATCH`:
+
+```text
+MAJOR.MINOR.PATCH
+  |     |     \\-- Patch: Bug fixes, no API changes
+  |     \\-------- Minor: New features, backward compatible
+  \\-------------- Major: Breaking changes
+```
+
+- **Bump MAJOR** when removing public API or changing behavior incompatibly
+- **Bump MINOR** when adding backward-compatible features or deprecating APIs
+- **Bump PATCH** when fixing bugs or making compatible performance improvements
+
+### Entry Quality Rules
+
+- Describe user impact, not implementation details
+- Start entries with a clear verb (Add, Fix, Change, Remove)
+- Link issues or PRs when available
+- Flag breaking changes explicitly with migration guidance
+
+## See Also
+
+- [Changelog Entry Writing](changelog-entry-writing.md)
+- [Changelog Release Workflow](changelog-release-workflow.md)
+- [Documentation Updates](documentation-updates.md)
+- [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+
+## References
+
+- [Keep a Changelog Specification](https://keepachangelog.com/en/1.1.0/)
+- [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html)
+
+## Changelog
+
+| Version | Date       | Changes         |
+| ------- | ---------- | --------------- |
+| 1.0.0   | 2026-01-22 | Initial version |

package/.llm/skills/documentation/changelog-release-workflow.md

@@ -0,0 +1,249 @@
+---
+title: "Changelog Release Workflow"
+id: "changelog-release-workflow"
+category: "documentation"
+version: "1.0.0"
+created: "2026-01-22"
+updated: "2026-01-22"
+
+source:
+  repository: "wallstop/DxMessaging"
+  files:
+    - path: "CHANGELOG.md"
+    - path: "package.json"
+  url: "https://github.com/wallstop/DxMessaging"
+
+tags:
+  - "changelog"
+  - "release-workflow"
+  - "versioning"
+  - "automation"
+  - "keep-a-changelog"
+
+complexity:
+  level: "basic"
+  reasoning: "Requires consistent release discipline and correct version/link formatting"
+
+impact:
+  performance:
+    rating: "none"
+    details: "Documentation only, no runtime impact"
+  maintainability:
+    rating: "high"
+    details: "Release workflow keeps changelog accurate and easy to navigate"
+  testability:
+    rating: "none"
+    details: "Documentation does not affect testability"
+
+prerequisites:
+  - "Understanding of semantic versioning"
+
+dependencies:
+  packages: []
+  skills:
+    - "changelog-management"
+
+applies_to:
+  languages:
+    - "Markdown"
+  frameworks:
+    - "Unity"
+    - ".NET"
+
+aliases:
+  - "Release notes workflow"
+  - "Changelog release process"
+
+related:
+  - "changelog-management"
+  - "changelog-entry-writing"
+  - "documentation-updates"
+
+status: "stable"
+---
+
+# Changelog Release Workflow
+
+> **One-line summary**: Keep the changelog accurate through a disciplined Unreleased workflow, consistent version formatting, and correct link updates.
+
+## Overview
+
+A changelog is only useful if the Unreleased section is maintained during development and converted correctly during releases. This skill defines how to manage Unreleased entries, cut a release, and keep version links accurate.
+
+## Problem Statement
+
+Common release mistakes include:
+
+- Unreleased items never moved to a versioned section
+- Missing or inconsistent dates and version formats
+- Broken compare links at the bottom of the file
+- Mixing per-package changes in a single changelog without structure
+
+## Solution
+
+### Unreleased Section Workflow
+
+1. **During development**: Add entries to `[Unreleased]` as changes are made
+1. **Before release**: Move `[Unreleased]` content to a new version section
+1. **At release**: Add date and version links
+1. **After release**: Create a fresh, empty `[Unreleased]` section
+
+#### Converting to a Release
+
+**Before**:
+
+```markdown
+## [Unreleased]
+
+### Added
+
+- New feature X
+```
+
+**After**:
+
+```markdown
+## [Unreleased]
+
+## [2.2.0] - 2026-01-22
+
+### Added
+
+- New feature X
+```
+
+### Date and Version Formats
+
+Use ISO 8601 dates and semantic versions in brackets:
+
+```markdown
+## [2.1.4] - 2026-01-22
+```
+
+- Valid: `[2.1.4]`
+- Valid: `[3.0.0]`
+- Invalid: `v2.1.4` (no 'v' prefix in header)
+- Invalid: `2.1.4` (missing brackets)
+
+### Version Links
+
+Add reference-style links at the bottom of the file:
+
+```markdown
+[Unreleased]: https://github.com/wallstop/DxMessaging/compare/v2.1.4...HEAD
+[2.1.4]: https://github.com/wallstop/DxMessaging/compare/v2.1.3...v2.1.4
+[2.1.3]: https://github.com/wallstop/DxMessaging/compare/v2.1.2...v2.1.3
+[2.1.2]: https://github.com/wallstop/DxMessaging/releases/tag/v2.1.2
+```
+
+Note: The oldest version links to its release tag, not a comparison.
+
+## Variations
+
+### Variation A: Single CHANGELOG.md (Recommended)
+
+```text
+repository/
+|- CHANGELOG.md
+|- package.json
+`- ...
+```
+
+**When to use**: Most projects, especially libraries and packages.
+
+### Variation B: Per-Package Changelogs
+
+```text
+repository/
+|- packages/
+|  |- core/
+|  |  |- CHANGELOG.md
+|  |  `- package.json
+|  `- unity/
+|     |- CHANGELOG.md
+|     `- package.json
+`- CHANGELOG.md
+```
+
+**When to use**: Monorepos with multiple published packages.
+
+### Variation C: GitHub Releases as Changelog
+
+**Pros**:
+
+- Integrated with release workflow
+- Links naturally to commits and PRs
+- Supports assets and binaries
+
+**Cons**:
+
+- Harder to view historical changes
+- Not portable (tied to GitHub)
+- Less control over formatting
+
+### Variation D: Generated Changelogs
+
+Tools like `conventional-changelog` can generate changelogs from commit messages:
+
+```bash
+npx conventional-changelog -p angular -i CHANGELOG.md -s
+```
+
+**When to use**: Teams with strict commit message conventions who want automation.
+
+## Usage Examples
+
+### Example: Complete Version Entry
+
+```markdown
+## [2.2.0] - 2026-01-20
+
+### Added
+
+- `MessageBus.EmitAsync` for asynchronous message delivery in non-Unity contexts
+- `IMessageInterceptor` interface for pre-processing messages before delivery
+- Support for message priority ordering via `[MessagePriority]` attribute
+- New `PooledMessage<T>` base class for zero-allocation messaging patterns
+
+### Changed
+
+- Improved broadcast message routing performance by 25% through internal caching
+- `MessageRegistrationToken` now implements `IEquatable<MessageRegistrationToken>`
+
+### Fixed
+
+- Fixed race condition in `MessageBus.Dispose` when called during active message delivery
+- Corrected memory leak when repeatedly registering/unregistering handlers in Editor mode
+
+### Deprecated
+
+- `MessageBus.RegisterHandler(Type, Delegate)` - use generic `RegisterHandler<T>` instead
+```
+
+## Testing Considerations
+
+While changelogs are not unit-tested, validate format in CI:
+
+```yaml
+- name: Validate Changelog
+  run: |
+    grep -q "## \[Unreleased\]" CHANGELOG.md
+    PACKAGE_VERSION=$(jq -r .version package.json)
+    grep -q "## \[${PACKAGE_VERSION}\]" CHANGELOG.md
+```
+
+## See Also
+
+- [Changelog Management](changelog-management.md)
+- [Changelog Entry Writing](changelog-entry-writing.md)
+- [Documentation Updates](documentation-updates.md)
+
+## References
+
+- [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+
+## Changelog
+
+| Version | Date       | Changes         |
+| ------- | ---------- | --------------- |
+| 1.0.0   | 2026-01-22 | Initial version |

package/.llm/skills/documentation/documentation-code-samples.md

@@ -0,0 +1,262 @@
+---
+title: "Documentation Code Samples"
+id: "documentation-code-samples"
+category: "documentation"
+version: "1.1.0"
+created: "2026-01-22"
+updated: "2026-01-22"
+
+source:
+  repository: "wallstop/DxMessaging"
+  files:
+    - path: "docs/"
+    - path: "README.md"
+  url: "https://github.com/wallstop/DxMessaging"
+
+tags:
+  - "documentation"
+  - "code-samples"
+  - "examples"
+  - "testing"
+  - "accuracy"
+  - "linting"
+  - "anti-patterns"
+
+complexity:
+  level: "basic"
+  reasoning: "Requires maintaining runnable examples that match current APIs"
+
+impact:
+  performance:
+    rating: "none"
+    details: "Documentation only"
+  maintainability:
+    rating: "high"
+    details: "Accurate samples reduce user confusion and support load"
+  testability:
+    rating: "medium"
+    details: "Samples should be verified with tests or compilation checks"
+
+prerequisites:
+  - "Understanding of the DxMessaging API surface"
+
+dependencies:
+  packages: []
+  skills:
+    - "documentation-updates"
+
+applies_to:
+  languages:
+    - "C#"
+    - "Markdown"
+  frameworks:
+    - "Unity"
+    - ".NET"
+
+aliases:
+  - "Doc examples"
+  - "Sample code standards"
+
+related:
+  - "documentation-updates"
+  - "documentation-style-guide"
+  - "documentation-update-workflow"
+  - "link-quality-guidelines"
+
+status: "stable"
+---
+
+# Documentation Code Samples
+
+> **One-line summary**: Code samples must compile, include context, and use the latest APIs.
+
+## Overview
+
+Docs are only as good as their samples. Every snippet should be copy-paste ready and reflect the current API surface.
+
+## Problem Statement
+
+Broken or incomplete samples cause:
+
+- User frustration and support tickets
+- Incorrect usage patterns spreading through copy/paste
+- Reduced trust in the documentation
+
+## Solution
+
+### Code Sample Requirements
+
+All code samples must be:
+
+1. **Correct** - Compiles without errors
+1. **Complete** - Includes required `using` statements and context
+1. **Current** - Uses the latest API, not deprecated patterns
+1. **Tested** - Verified to actually work
+
+### Good Code Sample
+
+```csharp
+using DxMessaging.Core;
+using DxMessaging.Core.Attributes;
+using DxMessaging.Unity;
+using UnityEngine;
+
+[DxTargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct DamageMessage
+{
+    public readonly int amount;
+    public readonly InstanceId source;
+}
+
+public sealed class HealthComponent : MessageAwareComponent
+{
+    [SerializeField]
+    private int currentHealth = 100;
+
+    protected override void RegisterMessageHandlers()
+    {
+        base.RegisterMessageHandlers();
+        _ = _messageRegistrationToken.RegisterGameObjectTargeted<DamageMessage>(
+            gameObject,
+            HandleDamage
+        );
+    }
+
+    private void HandleDamage(ref DamageMessage message)
+    {
+        currentHealth -= message.amount;
+        Debug.Log($"Took {message.amount} damage from {message.source}. Health: {currentHealth}");
+    }
+}
+```
+
+### Bad Code Sample (Anti-Pattern)
+
+```csharp
+// Missing using statements
+// Missing class context
+// Uses outdated API
+
+public void HandleDamage(DamageMessage msg)  // Wrong signature! Should be (ref DamageMessage message)
+{
+    health -= msg.damage;  // Field doesn't exist in example - should be msg.amount
+}
+```
+
+### Code Fence Language for Anti-Pattern Examples
+
+When showing examples of **bad patterns** (anti-patterns) in documentation, especially for Markdown syntax, use `text` or `none` as the code fence language instead of `markdown`:
+
+````markdown
+<!-- GOOD: Use 'text' for anti-pattern examples that might trigger linters -->
+
+```text
+<!-- BAD: Raw file names as link text -->
+See [README.md](../README.md) for installation.
+```
+````
+
+#### Why this matters
+
+- Documentation linters may scan for patterns like raw file names in link text
+- Using `text` or `none` signals that the content is illustrative, not actual documentation
+- Some linting tools only check content in `markdown` code blocks
+- Prevents false positives in CI/CD pipelines
+
+For non-Markdown anti-patterns (like C# code), using the actual language (`csharp`) is still appropriate since code linters typically don't run on documentation files.
+
+### Anti-Patterns to Avoid
+
+#### Bad: Outdated Examples
+
+````markdown
+## Emitting Messages
+
+```csharp
+// Old API - no longer works!
+MessageBus.Instance.Send(new DamageEvent());
+```
+````
+
+#### Bad: Missing Version Context
+
+```markdown
+## New Feature
+
+Use the new interceptor API to preprocess messages...
+```
+
+Fix with a version annotation:
+
+```markdown
+## Message Interceptors
+
+> **Added in v2.1.0**
+
+Use interceptors to preprocess messages...
+```
+
+#### Bad: Incomplete Code Samples
+
+```csharp
+// Register the handler
+_messageRegistrationToken.RegisterGameObjectTargeted<DamageMessage>(gameObject, OnDamage);
+
+// Handle the message
+private void OnDamage(DamageMessage msg) { ... }  // Wrong signature and missing context
+```
+
+## Testing Considerations
+
+### Verifying Code Samples Compile
+
+Extract and compile samples in CI where possible:
+
+```csharp
+[Test]
+public void DocumentedDamageMessagePatternCompiles()
+{
+    MessageBus messageBus = new MessageBus();
+    MessageRegistrationToken token = messageBus.CreateRegistrationToken();
+
+    int damageReceived = 0;
+    MessageRegistrationHandle handle = token.RegisterUntargeted<SimpleUntargetedMessage>(
+        (ref SimpleUntargetedMessage msg) => damageReceived++
+    );
+
+    SimpleUntargetedMessage message = new SimpleUntargetedMessage();
+    messageBus.UntargetedEmit(ref message);
+
+    Assert.AreEqual(1, damageReceived, "Handler should have been invoked exactly once");
+
+    handle.Dispose();
+    token.Dispose();
+}
+```
+
+### Documentation Review Checklist
+
+- [ ] All code samples paste into a real project without errors
+- [ ] API method names match the actual codebase
+- [ ] Handler signatures use `ref TMessage` pattern
+- [ ] Version annotations are accurate
+- [ ] Links to related docs work
+
+## See Also
+
+- [Documentation Updates](documentation-updates.md)
+- [Documentation Style Guide](documentation-style-guide.md)
+- [Documentation Update Workflow](documentation-update-workflow.md)
+- [Link Quality Guidelines](link-quality-guidelines.md)
+
+## References
+
+- [Unity Best Practice Guides](https://docs.unity3d.com/Manual/best-practice-guides.html)
+
+## Changelog
+
+| Version | Date       | Changes                                                  |
+| ------- | ---------- | -------------------------------------------------------- |
+| 1.1.0   | 2026-01-22 | Added guidance on code fence languages for anti-patterns |
+| 1.0.0   | 2026-01-22 | Initial version                                          |