docs: split hello world tutorial into two (send and receive) #2981
Conversation
quetzalliwrites
added
📑 docs
area/docs
✅ Deploy Preview for asyncapi-website ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site configuration. |
asyncapi-bot
requested review from
sambhavgupta0705,
BhaswatiRoy,
J0SAL,
TRohit20 and
VaishnaviNandakumar
quetzalliwrites
requested review from
derberg,
J0SAL,
VaishnaviNandakumar and
TRohit20
and removed request for
VaishnaviNandakumar,
J0SAL,
BhaswatiRoy,
sambhavgupta0705 and
TRohit20
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-2981--asyncapi-website.netlify.app/ |
pages/docs/tutorials/getting-started/hello-world-send-message.md
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Kindly change the folder for these files, as inside markdown.
There was a problem hiding this comment.
Got it, thanks for the reminder!
|
what happens with https://github.com/asyncapi/website/blob/master/markdown/docs/tutorials/getting-started/hello-world.md tutorial? shouldn't one of new once replace it with same filename but different title (asking because of dead links) |
|
|
||
| The `operations` section is where you describe what the application is doing. Each operation has a unique identifier for example, `sendHello`. | ||
|
|
||
| In the above example, you see that the `Hello world application` is a producer sending the `sayHelloMessage` message from the `hello` channel. In other words, you can say that the `Hello world application` publishes the `hello` topic to `send` the `sayHelloMessage` message. That AsyncAPI document describes what the `Hello world application` is doing, not what others can do with it. |
There was a problem hiding this comment.
| In the above example, you see that the `Hello world application` is a producer sending the `sayHelloMessage` message from the `hello` channel. In other words, you can say that the `Hello world application` publishes the `hello` topic to `send` the `sayHelloMessage` message. That AsyncAPI document describes what the `Hello world application` is doing, not what others can do with it. | |
| In the above example, you see that the `Hello world application` is a producer sending the `sayHelloMessage` message to the `hello` channel. In other words, you can say that the `Hello world application` `send` the `sayHelloMessage` message to the `hello` topic. That AsyncAPI document describes what the `Hello world application` is doing, not what others can do with it. |
| @@ -0,0 +1,120 @@ | |||
| --- | |||
| title: "Receive 'Hello world' message" | |||
There was a problem hiding this comment.
the only difference in this document is receive operation and there is a lot of repetition - is it intended? especially that app name is the same Hello world application. Shouldn't it be done like other tuturials for example for Kafka, where first tutorial would be about send message, and the one about receiving would be "extending" the send-one, where you extend the document with additional receive operation (of course still explaining these can be separate)
|
There would no longer be that link. Instead, we would have two new links that help differentiate the two hello world tutorials in this section. As for dead links, I will make sure to check for any in this PR too now that it's being reviewed. |
|
then we need redirect from old link to a new one, for external resources that link to the current document, to not cause dead links |
|
Oh, right! I forgot, thanks for reminding me. smh 🤦♀️ Can you remind/tell me where I should be adding the redirect links? I remember before I did it for the spec docs, but this is the website repo and I'm unsure. 🫤 |
|
/update |
|
@quetzalliwrites @derberg Any update on this PR? |
|
This pull request has been automatically marked as stale because it has not had recent activity 😴 It will be closed in 120 days if no further activity occurs. To unstale this pull request, add a comment with detailed explanation. There can be many reasons why some specific pull request has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model. Let us figure out together how to push this pull request forward. Connect with us through one of many communication channels we established here. Thank you for your patience ❤️ |
WalkthroughTwo new tutorial documents have been added. One document demonstrates building a consumer application that receives a "hello {name}" message via an AsyncAPI spec with a receiveHello operation. The other document outlines creating a producer application that sends a "hello {name}" message using an AsyncAPI spec with a sendHello operation. Both documents detail the AsyncAPI components such as the info, channels, and operations sections, emphasizing message structure validation via a regex pattern. Changes
Sequence Diagram(s)sequenceDiagram
participant Producer as Producer Application
participant Broker as AsyncAPI Broker
Producer->>Broker: Execute sendHello operation with "hello {name}"
Broker-->>Producer: (Optional) Acknowledge message publish
sequenceDiagram
participant Broker as AsyncAPI Broker
participant Consumer as Consumer Application
Broker->>Consumer: Deliver "hello {name}" via receiveHello operation
Consumer-->>Broker: (Optional) Acknowledge message receipt
Assessment against linked issues
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #2981 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 20 20
Lines 732 732
=========================================
Hits 732 732 ☔ View full report in Codecov by Sentry. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (6)
pages/docs/tutorials/getting-started/hello-world-send-message.md (3)
52-70: Info Object Explanation and Versioning NoteThe snippet clearly presents the
infoobject. As a minor improvement, consider rephrasing the versioning note for brevity (for example, “It is recommended to update the version whenever changes are made.”).
94-94: Conciseness Suggestion for Channels DescriptionThe sentence “The
channelssection of the specification houses all of the mediums where messages flow through.” can be streamlined by removing “of” (e.g., “...houses all mediums where messages flow through.”).🧰 Tools
🪛 LanguageTool
[style] ~94-~94: Consider removing “of” to be more concise
Context: ...ls` section of the specification houses all of the mediums where messages flow through. Fo...(ALL_OF_THE)
120-121: Punctuation for ClarityConsider adding a comma after “identifier” in the sentence “Each operation has a unique identifier for example,
sendHello” — it would read better as “Each operation has a unique identifier, for example,sendHello.”pages/docs/tutorials/getting-started/hello-world-receive-message.md (3)
52-70: Info Object Explanation and Versioning NoteThis snippet thoroughly explains the
infoobject. As with the sending tutorial, consider rephrasing the versioning recommendation for brevity.
94-94: Conciseness Suggestion for Channels DescriptionAs in the send tutorial, consider removing “of” to improve conciseness in the sentence describing the channels section.
🧰 Tools
🪛 LanguageTool
[style] ~94-~94: Consider removing “of” to be more concise
Context: ...ls` section of the specification houses all of the mediums where messages flow through. Fo...(ALL_OF_THE)
[uncategorized] ~94-~94: Possible missing comma found.
Context: ... kinds of information flow through each channel similar to the analogy of TV channels. ...(AI_HYDRA_LEO_MISSING_COMMA)
118-121: Punctuation for ClarityA comma after “identifier” in the sentence “Each operation has a unique identifier for example,
receiveHello” would enhance readability (e.g., “..., for example,receiveHello”).🧰 Tools
🪛 LanguageTool
[uncategorized] ~118-~118: Possible missing comma found.
Context: ...n is doing. Each operation has a unique identifier for example,receiveHello. In the ab...(AI_HYDRA_LEO_MISSING_COMMA)
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
pages/docs/tutorials/getting-started/hello-world-receive-message.md(1 hunks)pages/docs/tutorials/getting-started/hello-world-send-message.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
pages/docs/tutorials/getting-started/hello-world-send-message.md
[style] ~72-~72: Consider shortening or rephrasing this to strengthen your wording.
Context: ...nded to change the version whenever you make changes to the API. <CodeBlock highlightedLines={...
(MAKE_CHANGES)
[style] ~94-~94: Consider removing “of” to be more concise
Context: ...ls` section of the specification houses all of the mediums where messages flow through. Fo...
(ALL_OF_THE)
[uncategorized] ~118-~118: Possible missing comma found.
Context: ...n is doing. Each operation has a unique identifier for example, sendHello. In the above...
(AI_HYDRA_LEO_MISSING_COMMA)
pages/docs/tutorials/getting-started/hello-world-receive-message.md
[style] ~72-~72: Consider shortening or rephrasing this to strengthen your wording.
Context: ...nded to change the version whenever you make changes to the API. <CodeBlock highlightedLines={...
(MAKE_CHANGES)
[style] ~94-~94: Consider removing “of” to be more concise
Context: ...ls` section of the specification houses all of the mediums where messages flow through. Fo...
(ALL_OF_THE)
[uncategorized] ~94-~94: Possible missing comma found.
Context: ... kinds of information flow through each channel similar to the analogy of TV channels. ...
(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~96-~96: Possible missing comma found.
Context: ...he given regular expression in a string format such as hello {name}. <CodeBlock hig...
(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~118-~118: Possible missing comma found.
Context: ...n is doing. Each operation has a unique identifier for example, receiveHello. In the ab...
(AI_HYDRA_LEO_MISSING_COMMA)
🔇 Additional comments (9)
pages/docs/tutorials/getting-started/hello-world-send-message.md (4)
1-4: YAML Frontmatter ValidityThe header is well structured with a clear title and weight assigned. This frontmatter sets up the document correctly.
8-26: AsyncAPI Specification Example – Send OperationThis code block provides a complete AsyncAPI example for a producer application. The use of
action: 'send'here correctly reflects the tutorial’s intent for sending messages.
30-48: Detailed Code Example – Full Document IllustrationThe detailed code block reiterates the AsyncAPI document in a highlighted manner. It effectively reinforces the structure outlined above.
74-92: Additional Info Block ExampleThis section further illustrates the API’s detail and is clear in its presentation. No issues noted.
pages/docs/tutorials/getting-started/hello-world-receive-message.md (5)
1-4: YAML Frontmatter ValidityThe header is correctly configured with a concise title and an appropriate weight, ensuring the document is properly identified in the navigation structure.
8-26: AsyncAPI Specification Example – Receive OperationThis code block provides a complete AsyncAPI example tailored for a consumer application. The operation
receiveHellowithaction: 'receive'is correctly used here.
30-48: Detailed Code Example – Full Document IllustrationThe highlighted example reaffirms the overall structure of the API specification. It clearly distinguishes the document’s components and is consistent with the receiving context.
74-92: Additional Info Block ExampleThis block well illustrates the essential detail of the API’s information. Everything appears in order.
98-116: Operation Details – Receive ContextThe code block for the channels section correctly defines the receive operation (
receiveHello) withaction: 'receive', which aligns with the tutorial’s purpose for consuming messages.
| <CodeBlock highlightedLines={[13,14,15,16,17]}> | ||
| {`asyncapi: 3.0.0 | ||
| info: | ||
| title: Hello world application | ||
| version: '0.1.0' | ||
| channels: | ||
| hello: | ||
| address: 'hello' | ||
| messages: | ||
| sayHelloMessage: | ||
| payload: | ||
| type: string | ||
| pattern: '^hello .+$' | ||
| operations: | ||
| sendHello: | ||
| action: 'receive' | ||
| channel: | ||
| $ref: '#/channels/hello'`} | ||
| </CodeBlock> |
There was a problem hiding this comment.
Operation Action Inconsistency
Within this highlighted example for the channels section, the sendHello operation mistakenly uses action: 'receive' instead of action: 'send'. Please update this to maintain consistency with the tutorial’s focus on sending messages.
Proposed change:
- action: 'receive'
+ action: 'send'📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| <CodeBlock highlightedLines={[13,14,15,16,17]}> | |
| {`asyncapi: 3.0.0 | |
| info: | |
| title: Hello world application | |
| version: '0.1.0' | |
| channels: | |
| hello: | |
| address: 'hello' | |
| messages: | |
| sayHelloMessage: | |
| payload: | |
| type: string | |
| pattern: '^hello .+$' | |
| operations: | |
| sendHello: | |
| action: 'receive' | |
| channel: | |
| $ref: '#/channels/hello'`} | |
| </CodeBlock> | |
| <CodeBlock highlightedLines={[13,14,15,16,17]}> | |
| {`asyncapi: 3.0.0 | |
| info: | |
| title: Hello world application | |
| version: '0.1.0' | |
| channels: | |
| hello: | |
| address: 'hello' | |
| messages: | |
| sayHelloMessage: | |
| payload: | |
| type: string | |
| pattern: '^hello .+$' | |
| operations: | |
| sendHello: | |
| action: 'send' | |
| channel: | |
| $ref: '#/channels/hello'`} | |
| </CodeBlock> |
Resolves #993 and comment by @derberg via #993 (comment).
Summary by CodeRabbit