docs: align Akka guidance with release notes#1
Conversation
📝 WalkthroughWalkthroughThis PR introduces comprehensive release-notes-aligned clean-code guidance for Akka SDK development. A new release-notes-guidance.md document captures version references, recent capability changes, and clean-code implications, then cascades those updates through existing guidance documents and updates navigation, build integration, and testing strategy. ChangesRelease-Aligned Clean Code Guidance
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/release-notes-guidance.md`:
- Around line 9-11: Update the release-notes snippet so the Akka SDK line reads
"Akka SDK 3.5.18" instead of "Akka SDK 3.5.19"; leave "Akka CLI 3.0.62"
unchanged; for the "Akka Runtime 1.5.48-1.5.52" entry keep the range only if the
May 2026 release notes explicitly state that range, otherwise replace it with
the single confirmed latest runtime version (1.5.52) to avoid suggesting an
incorrect range.
- Around line 42-43: Update the release notes guidance to correct the annotation
name: replace the incorrect `@AgentDescriptor` mention with the intended
`@AgentDescription` (or clarify if the text meant something else), and ensure
the guidance still references `@AgentRole` as the current agent role annotation;
update any sentences that contrast `@AgentRole` and `@AgentDescription` so they
accurately reflect deprecation/usage.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 2010dd22-c71c-4a72-a59a-0944138bfbe7
📒 Files selected for processing (9)
README.mddocs/README.mddocs/component-playbook.mddocs/release-notes-guidance.mddocs/review-checklist.mddocs/source-notes.mddocs/testing-strategy.mdscripts/build-site.mjsscripts/check-markdown.mjs
| - Akka SDK 3.5.19 | ||
| - Akka CLI 3.0.62 | ||
| - Akka Runtime 1.5.48-1.5.52 in the May 2026 notes |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
What are the latest Akka SDK, Akka CLI, and Akka Runtime versions as of May 2026?
💡 Result:
As of May 24, 2026, the latest versions for the Akka platform components are as follows: Akka SDK: The latest version is v3.5.18, released on April 16, 2026 [1][2]. Akka CLI: The latest version is 3.0.62, as referenced in official installation documentation [3]. Akka Runtime: The latest version integrated into the Akka SDK is 1.5.52 [2][4]. Please note that Akka and Akka.NET are distinct projects. The versions above refer to the Akka platform (often associated with the Akka SDK and Kalix-based services) [1][2][5]. Akka.NET, the separate.NET implementation, maintains its own independent release cycle, with versions such as 1.5.68 available as of May 2026 [6].
Citations:
- 1: https://github.com/akka/akka-sdk/releases/tag/v3.5.18
- 2: https://github.com/akka/akka-sdk/releases
- 3: https://doc.akka.io/operations/cli/installation.html
- 4: Auto PR - Akka Runtime version 1.5.52 akka/akka-sdk#1584
- 5: https://doc.akka.io/index.html
- 6: https://github.com/akkadotnet/akka.net/releases/tag/1.5.68
Fix Akka SDK version in release-notes guidance
- The snippet’s “Akka SDK 3.5.19” conflicts with the latest official Akka SDK release version (v3.5.18); update it to v3.5.18.
- “Akka CLI 3.0.62” matches the latest official CLI version, and Akka Runtime latest is 1.5.52—so keep the 1.5.48–1.5.52 range only if it’s explicitly stated in the May 2026 release notes.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/release-notes-guidance.md` around lines 9 - 11, Update the release-notes
snippet so the Akka SDK line reads "Akka SDK 3.5.18" instead of "Akka SDK
3.5.19"; leave "Akka CLI 3.0.62" unchanged; for the "Akka Runtime 1.5.48-1.5.52"
entry keep the range only if the May 2026 release notes explicitly state that
range, otherwise replace it with the single confirmed latest runtime version
(1.5.52) to avoid suggesting an incorrect range.
| - Use `@AgentRole` for the agent role annotation in current code; do not add new | ||
| `@AgentDescriptor` examples. |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Akka SDK agent annotation @AgentRolevs@AgentDescriptor``
💡 Result:
In Akka SDK (agent components), @AgentRole is the newer annotation for specifying an agent’s “role”, and @AgentDescriptor is legacy/old-style agent metadata that has been deprecated. 1) What @AgentRole is for - The Akka SDK migration guide states that Akka SDK 3.5.5 deprecates @AgentDescription in favor of using @Component (for agent metadata like name/description) and the new @AgentRole annotation for specifying agent roles. It also notes the framework gives more consistent API aligned with other component types. [1] 2) What @AgentDescriptor / @AgentDescription is for (and its status) - The same migration guide explicitly says “The @AgentDescription annotation is now deprecated.” [1] - It further says you can migrate any @AgentDescription.role field by adding @AgentRole instead. [1] 3) How metadata is expressed after migration (practical difference) - Old pattern (deprecated): you’d use @AgentDescription(name=..., description=..., role=...) on the agent class. [1] - New pattern: put name/description into @Component(name=..., description=...) and put role into @AgentRole("...") on the agent class. [1] 4) Guidance / rule of thumb - Use @Component for agent name and description, and use @AgentRole(...) for the role (e.g., “worker”, “planner”, etc.). [1] - Do not try to use both the old and new styles for the same fields (e.g., you can’t mix @AgentDescription.name with @Component.name); the migration guide warns this will cause validation errors. [1] If by “@AgentDescriptor” you meant a specific class/annotation name other than what Akka documents as “@AgentDescription”, tell me the exact fully-qualified annotation name (package + class) from your codebase and I’ll map it precisely to the current Akka annotations.
Citations:
Fix agent annotation name in release notes guidance (@AgentDescriptor → @AgentDescription).
Akka’s migration guidance positions @AgentRole as the current agent role annotation and deprecates @AgentDescription (not @AgentDescriptor). Update the doc text to use @AgentDescription or clarify what @AgentDescriptor is intended to refer to.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/release-notes-guidance.md` around lines 42 - 43, Update the release
notes guidance to correct the annotation name: replace the incorrect
`@AgentDescriptor` mention with the intended `@AgentDescription` (or clarify if
the text meant something else), and ensure the guidance still references
`@AgentRole` as the current agent role annotation; update any sentences that
contrast `@AgentRole` and `@AgentDescription` so they accurately reflect
deprecation/usage.
1 participant
Summary
Test Plan
node scripts/check-markdown.mjsnode scripts/build-site.mjsSummary by CodeRabbit