docs: document new standalone declarative topics API#609
Open
mensfeld wants to merge 1 commit into
Open
Conversation
Rewrite the Declarative Topics documentation to feature the new standalone `declaratives.draw` DSL as the primary approach. The new API decouples topic declarations from routing, allowing management of any Kafka topic (including those not consumed by the application). Key additions: - Standalone `declaratives.draw` DSL with per-attribute methods - Defaults support for applying common settings across topics - Multiple draw blocks (additive) - Managing topics you do not consume - Coexistence and precedence rules with routing - Migration guide from legacy routing-based `config()` approach The legacy routing `config()` method is documented as deprecated but still functional for backwards compatibility.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR rewrites the “Declarative Topics” documentation to make the new standalone declaratives.draw DSL the primary way to declare/manage Kafka topics (including topics not consumed by the app), while documenting the routing config() approach as deprecated but still supported.
Changes:
- Updates examples and narrative to use standalone
declaratives.drawwith per-attribute methods (partitions,replication_factor,active, etc.). - Adds new documentation sections for managing non-consumed topics, defaults, multiple draw blocks, coexistence with routing, and a migration guide.
- Adds/updates limitations notes to reflect the new declaratives-centric topic management model.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+211
to
+214
| ## Coexistence with Routing | ||
|
|
||
| You can use Karafka to manage topics that you do not consume from as well by defining their config and making them inactive at the same time: | ||
| Declarative topics and routing are independent but share a single underlying repository. When a topic is declared in both places, the standalone `declaratives.draw` declaration takes precedence: | ||
|
|
Comment on lines
+216
to
+230
| class KarafkaApp < Karafka::App | ||
| # Standalone declaration wins | ||
| declaratives.draw do | ||
| topic :orders do | ||
| partitions 20 | ||
| replication_factor 3 | ||
| end | ||
| end | ||
|
|
||
| routes.draw do | ||
| topic :orders do | ||
| consumer OrdersConsumer | ||
| # This config is ignored because :orders was already declared above | ||
| config(partitions: 99) | ||
| end |
| - Topics management is enabled by default but will not be used unless any CLI commands are invoked. | ||
| - `migrate` does not wait for a confirmation. Use `plan` command to check the changes that would be applied. | ||
| - If a topic is used by several consumer groups defined in one application, only the first `config` defined will be used. | ||
| - If a topic is declared in both `declaratives.draw` and routing `config()`, the standalone declaration takes precedence. |
Comment on lines
203
to
206
| ``` | ||
|
|
||
| This will effectively ignore this topic from being altered in any way by Karafka. Karafka will ignore this topic together in all the CLI topics related operations. | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rewrite the Declarative Topics documentation to feature the new standalone
declaratives.drawDSL as the primary approach. The new API decouples topic declarations from routing, allowing management of any Kafka topic (including those not consumed by the application).Key additions:
declaratives.drawDSL with per-attribute methodsconfig()approachThe legacy routing
config()method is documented as deprecated but still functional for backwards compatibility.