Repository navigation
Conversation
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
magistrala-docs | 5af3b70 | Commit Preview URL Branch Preview URL |
Sep 10 2026, 03:02 PM |
…ing callouts
Several dev-guide pages carried red-flag <Callout type="warn"> blocks
announcing that examples predate the Atom/FluxMQ migration, describe
services that "no longer exist", or are "kept for historical reference
only". These read as public admissions of broken docs rather than
useful warnings, and in getting-started.mdx buried the current
workflow under dead CLI commands and stale log dumps.
- getting-started.mdx: drop the intro warning; replace the obsolete
`provision`/`messages` CLI walkthroughs with the current
workspaces/devices/channels create flow and HTTP publish example;
remove the dead SpiceDB "Authorization schema management" section;
rewrite the Message Broker section to lead with FluxMQ as default.
- authorization.mdx: drop the redundant SpiceDB warning (page already
documents the current Atom model).
- edge.mdx, dev-tools/{authorization,storage,authentication,events,
messaging}.mdx, entities.mdx: reword warnings to plain, confident
notes pointing at current docs, dropping "gone"/"dead code"/
"historical reference only" phrasing.
- services/consumers.mdx: remove the unreachable Notifiers/Subscriptions
API sections entirely instead of documenting them as dead code; keep
Writers, which is the real, current path.
Legitimate warnings (certs reachability, CLI/API equivalence gaps,
Enterprise Edition notes, gateway trust boundary, destructive-action
confirmations) were left untouched.
fbugarski
force-pushed
the
docs/remove-stale-warning-callouts
branch
from
September 9, 2026 16:23
ec7a445 to
6cd5881
Compare
fbugarski
changed the title
A source-verified pass across the docs (see the sibling PR on the same
base) turned up problems introduced or inherited by this branch's own
earlier edits:
- getting-started.mdx: "NATS remains available as a build-time
alternative" and the whole "Switching Brokers" section
(MG_BROKER_TYPE, vernemq/rabbitmq support) don't reflect reality —
there are zero NATS/RabbitMQ/VerneMQ references anywhere in the
current codebase, and no MG_BROKER_TYPE env var. FluxMQ is not an
alternative among several, it's the only broker. Replaced the
NATS-specific docker-compose override example with a FluxMQ one.
- dev-tools/events.mdx: this branch's own rewrite claimed the mqtt
adapter *currently* publishes to Redis Streams ("currently used by
the mqtt adapter"). There is no cmd/mqtt service anymore (FluxMQ
absorbs MQTT natively) and the implementing package
(pkg/messaging/events) has zero importers anywhere — corrected to
past tense and explicit about neither existing today.
- dev-tools/messaging.mdx: the "MQTT Broker" and "Message Broker"
sections described a fully fabricated pluggable-broker system (NATS
JetStream, RabbitMQ, Kafka, MG_BROKER_TYPE/MG_MQTT_BROKER_TYPE env
vars) with detailed internals for brokers that don't exist in the
codebase — go.mod's rabbitmq/amqp091-go dependency is FluxMQ's own
AMQP 0.9.1 client, not a RabbitMQ broker integration. Replaced ~140
lines with an accurate summary and cleaned up now-unused link
references and frontmatter keywords.
…rent fact Same fix as the sibling PR's architecture.mdx commit. NATS was never a real feature here -- explaining its absence at length repeats the exact anti-pattern this whole cleanup effort set out to remove. A reader has no reason to expect a NATS/RabbitMQ/Kafka alternative unless the docs tell them to look for one.
…istory Docs should describe what's true now, not a detailed record of what used to be true. This page's callout was already accurate about Redis Streams event publishing being dead everywhere, but left ~2300 lines of detailed historical examples (Users/Clients/Bootstrap/MQTT Adapter event payloads, Redis Stream commands, NATS JetStream output) sitting below it for something with zero current relevance -- same "looks unfinished" problem as the pages already trimmed (certs.mdx, consumers.mdx), just not caught in that pass since the claim itself happened to be true rather than fabricated. Replaced with a few sentences stating the current reality and pointing to Atom's audit log (Entities § Audit logs) as where this kind of tracking actually lives today.
This branch has not been deployed
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
1 participant
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
Several dev-guide pages carried red-flag
<Callout type="warn">blocks announcing that examples predate the Atom/FluxMQ migration, describe services that "no longer exist", or are "kept for historical reference only". These read as public admissions of broken docs rather than useful warnings, and ingetting-started.mdxburied the current workflow under dead CLI commands and stale log dumps.getting-started.mdx: dropped the intro warning; replaced the obsoleteprovision/messagesCLI walkthroughs with the currentworkspaces/devices/channels createflow and an HTTP publish example; removed the dead SpiceDB "Authorization schema management" section; rewrote the Message Broker section to lead with FluxMQ as the current default.authorization.mdx: dropped the redundant SpiceDB warning (page already documents the current Atom model).edge.mdx,dev-tools/{authorization,storage,authentication,events,messaging}.mdx,entities.mdx: reworded warnings into plain, confident notes pointing at current docs, dropping "gone"/"dead code"/"historical reference only" phrasing.services/consumers.mdx: removed the unreachable Notifiers/Subscriptions API sections entirely instead of documenting them as dead code; kept Writers, which is the real, current path.Legitimate warnings (certs reachability, CLI/API equivalence gaps, Enterprise Edition notes, gateway trust boundary, destructive-action confirmations) were left untouched.
Follow-up commit: a source-verified pass (checking every claim against the actual
magistrala/atomsource) found that this branch's own earlier edits had introduced or preserved factually wrong claims — a fabricated "NATS available as a build-time alternative" (there are zero NATS references anywhere in the current codebase), an entirely fictional pluggable-broker system indev-tools/messaging.mdx(NATS JetStream/RabbitMQ/Kafka internals,MG_BROKER_TYPEenv vars that don't exist), and a present-tense claim indev-tools/events.mdxthat themqttadapter currently publishes to Redis Streams (it doesn't exist anymore, and the implementing package has zero importers). All three are corrected in the second commit.Test plan
rgfor red-flag phrases (dead code,historical reference,predates,is gone, etc.) acrosscontent/docsreturns nothing<Callout type="warn">blocks individually reviewed and confirmed legitimatemagistrala,atomrepos) — see follow-up commitpnpm run lintpassespnpm run types:check(fumadocs-mdx + next typegen + tsc --noEmit) passes