docs: improve discoverability of replication factor/min.insync.replicas guidance #319
Conversation
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
…as guidance Add cross-links and warnings to help users find the comprehensive documentation about the common RF=MinISR misconfiguration: - Kafka/Topic-Configuration.md: Add warning admonition and See Also link - WaterDrop/Idempotence-and-Acknowledgements.md: Add warning and See Also section - FAQ.md: Enhance not_enough_replicas error section with misconfiguration guidance All links point to the detailed coverage in Broker-Failures-and-Fault-Tolerance.md
- Remove non-existent anchor from links to Broker-Failures doc - Generalize min.insync.replicas recommendation to apply to any cluster size
Contributor
There was a problem hiding this comment.
Pull request overview
This PR enhances the discoverability of critical guidance about the replication.factor / min.insync.replicas misconfiguration by adding warning admonitions and cross-links to the existing comprehensive documentation in Broker-Failures-and-Fault-Tolerance.md. The changes help users avoid a common mistake where setting both parameters equal (e.g., both to 2) causes write failures during routine broker maintenance.
- Added prominent warning boxes explaining the misconfiguration and its impact
- Created "See Also" cross-references linking related documentation
- Enhanced the FAQ entry for
not_enough_replicaserrors with explicit misconfiguration guidance
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
WaterDrop/Idempotence-and-Acknowledgements.md |
Added warning admonition after the min.insync.replicas configuration example and new "See Also" section with links to related documentation |
Kafka/Topic-Configuration.md |
Added warning admonition after the configuration table explaining the common misconfiguration and its consequences, plus additional "See Also" link |
FAQ.md |
Enhanced the "Not enough in-sync replicas" error troubleshooting section with explicit guidance about the RF=MinISR misconfiguration and link to detailed scenarios |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Reduce warnings to brief pointers to the comprehensive coverage in Broker-Failures-and-Fault-Tolerance.md
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.
Summary
replication.factor/min.insync.replicasmisconfiguration (e.g., setting both to 2)Broker-Failures-and-Fault-Tolerance.mdbut users weren't finding itChanges
Kafka/Topic-Configuration.mdWaterDrop/Idempotence-and-Acknowledgements.mdmin.insync.replicasexample + new See Also sectionFAQ.mdnot_enough_replicaserror section with explicit misconfiguration guidance and linkTest plan