docs: add onboarding guide for identifying good first issues #1815
Conversation
SaxenaAnushka102
requested review from
quetzalliwrites,
derberg,
asyncapi-bot-eve and
thulieblack
as code owners
|
@bandantonio your review |
WalkthroughA new onboarding guide titled "identifying-good-first-issues.md" has been added to the documentation. This guide provides instructions and tips for new contributors on how to find and work on beginner-friendly issues in AsyncAPI repositories, including explanations of GitHub labels and contribution processes. Changes
Sequence Diagram(s)sequenceDiagram
participant NewContributor
participant GitHub
participant Maintainer
NewContributor->>GitHub: Search for "good first issue" labels
NewContributor->>GitHub: Review issue details and labels
NewContributor->>GitHub: Comment to claim issue
Maintainer-->>NewContributor: Approve or provide guidance
NewContributor->>GitHub: Fork, branch, and work on issue
NewContributor->>Maintainer: Communicate for support if needed
Possibly related issues
Possibly related PRs
Suggested labels
Suggested reviewers
Poem
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. 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
CodeRabbit Configuration File (
|
![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 (3)
mentorship/asyncapi-mentorship/2024/project-ideas.md (1)
32-32: Ensure consistent table pipe style
The new row is missing a trailing pipe, which violates the project’stable-pipe-stylerule (MD055). Please add a|at the end of line 32 to match the header and alignment rows.-13 | [Technical Blog Posts on Integrating AsyncAPI with Kafka](https://github.com/orgs/asyncapi/discussions/1361#discussioncomment-10885096) | Docs | [Leonardo](https://github.com/leonardotorresaltez) +13 | [Technical Blog Posts on Integrating AsyncAPI with Kafka](https://github.com/orgs/asyncapi/discussions/1361#discussioncomment-10885096) | Docs | [Leonardo](https://github.com/leonardotorresaltez) |🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
32-32: Table pipe style
Expected: trailing_only; Actual: no_leading_or_trailing; Missing trailing pipe(MD055, table-pipe-style)
docs/onboarding-guide/identifying-good-first-issues.md (2)
31-33: Remove stray space before punctuation
Line 32 has an extra space before the period in “Issues” tab . It should read “Issues” tab.
87-87: Consider toning down exclamation marks
The closing sentence ends with an exclamation. While it conveys enthusiasm, reducing exclamation usage can improve readability and maintain a professional tone.🧰 Tools
🪛 LanguageTool
[style] ~87-~87: Using many exclamation marks might seem excessive (in this case: 10 exclamation marks for a text that’s 5055 characters long)
Context: ...d let’s build something awesome together!(EN_EXCESSIVE_EXCLAMATION)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/onboarding-guide/identifying-good-first-issues.md(1 hunks)mentorship/asyncapi-mentorship/2024/project-ideas.md(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
mentorship/asyncapi-mentorship/2024/project-ideas.md
32-32: Table pipe style
Expected: trailing_only; Actual: no_leading_or_trailing; Missing trailing pipe
(MD055, table-pipe-style)
🪛 LanguageTool
docs/onboarding-guide/identifying-good-first-issues.md
[grammar] ~5-~5: Did you mean the verb “finds”?
Context: ...yncAPI. ## Your First Contribution ### Find Something to Work On The first step in ...
(SENT_START_PRPS_JJ_NN_VBP)
[style] ~87-~87: Using many exclamation marks might seem excessive (in this case: 10 exclamation marks for a text that’s 5055 characters long)
Context: ...d let’s build something awesome together!
(EN_EXCESSIVE_EXCLAMATION)
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
docs/onboarding-guide/identifying-good-first-issues.md (3)
9-11: Remove manual H1 to avoid duplication
Since the docs site will render the page title from front matter, you can remove the# Start Contributing to AsyncAPIheading or convert it to a lower-level header (e.g.,##) to prevent duplicate titles on the page.
29-37: Use backticks for GitHub labels
To improve readability and distinguish labels from prose, consider rendering labels in code style, e.g.:- `good first issue` – These are beginner-friendly… - `help wanted` – These issues need attention…
38-50: Remove trailing colon in heading
Markdown linting discourages trailing punctuation in headings. Change:- ### How to Find These Issues: + ### How to Find These Issues🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
38-38: Trailing punctuation in heading
Punctuation: ':'(MD026, no-trailing-punctuation)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/onboarding-guide/identifying-good-first-issues.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/onboarding-guide/identifying-good-first-issues.md
[grammar] ~13-~13: Did you mean the verb “finds”?
Context: ...yncAPI. ## Your First Contribution ### Find Something to Work On The first step in ...
(SENT_START_PRPS_JJ_NN_VBP)
[style] ~95-~95: Using many exclamation marks might seem excessive (in this case: 10 exclamation marks for a text that’s 5061 characters long)
Context: ...d let’s build something awesome together!
(EN_EXCESSIVE_EXCLAMATION)
🪛 markdownlint-cli2 (0.17.2)
docs/onboarding-guide/identifying-good-first-issues.md
38-38: Trailing punctuation in heading
Punctuation: ':'
(MD026, no-trailing-punctuation)
🔇 Additional comments (6)
docs/onboarding-guide/identifying-good-first-issues.md (6)
1-7: Front matter looks correct
You've included all required fields (id,title,sidebar_label,description) plus aweightto control ordering. This aligns with AsyncAPI docs conventions.
12-14: Section headings are clear and structured
The## Your First Contributionand### Find Something to Work Onheadings effectively guide newcomers through the initial steps.🧰 Tools
🪛 LanguageTool
[grammar] ~13-~13: Did you mean the verb “finds”?
Context: ...yncAPI. ## Your First Contribution ### Find Something to Work On The first step in ...(SENT_START_PRPS_JJ_NN_VBP)
26-27: Helpful contributor warning
The callout about avoiding trivial PRs is on point and sets the right expectations for new contributors.
56-85: Issue labels table is comprehensive
The table clearly defines all common labels across AsyncAPI repos. Nice work providing this level of detail!
86-94: Next Steps section is actionable
The “first come, first served” workflow and fork-branch instructions are concise and helpful.
95-95: Engaging call to action
Ending with an encouraging invitation is a great way to motivate contributors.🧰 Tools
🪛 LanguageTool
[style] ~95-~95: Using many exclamation marks might seem excessive (in this case: 10 exclamation marks for a text that’s 5061 characters long)
Context: ...d let’s build something awesome together!(EN_EXCESSIVE_EXCLAMATION)
There was a problem hiding this comment.
You're off to a great start @SaxenaAnushka102! :)
Just gave some tips to make the file more beginner-friendly. Keep it up! :)
| id: identifying-good-first-issues | ||
| title: Identifying Good First Issues | ||
| sidebar_label: Identifying Good First Issues | ||
| description: A guide to help new contributors find and work on beginner-friendly issues in AsyncAPI projects | ||
| weight: 50 |
There was a problem hiding this comment.
The id & sidebar components are not needed
| id: identifying-good-first-issues | |
| title: Identifying Good First Issues | |
| sidebar_label: Identifying Good First Issues | |
| description: A guide to help new contributors find and work on beginner-friendly issues in AsyncAPI projects | |
| weight: 50 | |
| title: Identifying Good First Issues | |
| description: A guide to help new contributors find and work on beginner-friendly issues in AsyncAPI projects | |
| weight: 50 |
| 2. Click on the "Issues" tab . | ||
| 3. Use the search bar to filter beginner-friendly issues: |
There was a problem hiding this comment.
Hey @thulieblack. Since this document is mostly for people who are very new to open source projects, I'm thinking adding screenshots of the two steps would be helpful. It could give these individuals a clearer idea on how to find beginner-friendly issues. What do you think?
| AsyncAPI follows a "first come, first served" approach for issue assignment: | ||
|
|
||
| - Comment on the issue – Start with saying something like, "Hey, I’d like to work on this!" so maintainers know you're interested. | ||
| - We do not pre-assign issues. Instead, contributors must comment on an issue they want to work on. | ||
| - Once you comment, wait for approval by maintainers. They may guide you further (if needed) or might assign the issue to you. If there are no blockers, you can start working! | ||
| - Start coding! – Once approved, fork the repository, create a new branch, and start working! | ||
| - Ask for help – Don’t hesitate to ask in the issue comments or the dedicated AsyncAPI Slack Channel if you’re stuck. |
There was a problem hiding this comment.
You're off to a great start! :) Just gave some ideas on how to make this portion a bit more readable
| AsyncAPI follows a "first come, first served" approach for issue assignment: | |
| - Comment on the issue – Start with saying something like, "Hey, I’d like to work on this!" so maintainers know you're interested. | |
| - We do not pre-assign issues. Instead, contributors must comment on an issue they want to work on. | |
| - Once you comment, wait for approval by maintainers. They may guide you further (if needed) or might assign the issue to you. If there are no blockers, you can start working! | |
| - Start coding! – Once approved, fork the repository, create a new branch, and start working! | |
| - Ask for help – Don’t hesitate to ask in the issue comments or the dedicated AsyncAPI Slack Channel if you’re stuck. | |
| AsyncAPI follows a "first come, first served" approach for assigning issues. Here are some tips to help you increase your chances of getting assigned to an issue: | |
| - **Comment on the issue:** Start with saying something like, "Hey, I’d like to work on this!" so maintainers know you're interested. | |
| >⚠ Note: We do not pre-assign issues. Instead, contributors must comment on an issue they want to work on. | |
| - **Once you comment, wait for approval by maintainers:** They may guide you further (if needed) or might assign the issue to you. If there are no blockers, you can start working! | |
| - **Start coding**: Once approved, [fork the repository](https://github.com/asyncapi/community/blob/master/git-workflow.md#fork-a-repository), [create a new branch](https://github.com/asyncapi/community/blob/master/git-workflow.md#start-contributing), and start working! | |
| - **Ask for help**: Don’t hesitate to ask in the issue comments or the dedicated AsyncAPI Slack Channel if you’re stuck. |
There was a problem hiding this comment.
@CBID2 On line 92, I would suggest linking to the Git Workflow document as it contains instructions specific to AsyncAPI instead of generic ones.
There was a problem hiding this comment.
Thanks for the reviews and the detailed explanation to all the changes, @CBID2 and @bandantonio 🙏
| - Improve the documentation (fix typos, enhance explanations, add examples). | ||
|
|
||
| - Clarify code comments, improve variable names, or refactor code. | ||
|
|
||
| - Add test coverage for untested areas. | ||
|
|
||
| - Help triage issues (identify duplicates, provide additional context). |
There was a problem hiding this comment.
| - Improve the documentation (fix typos, enhance explanations, add examples). | |
| - Clarify code comments, improve variable names, or refactor code. | |
| - Add test coverage for untested areas. | |
| - Help triage issues (identify duplicates, provide additional context). | |
| - Improve the documentation (fix typos, enhance explanations, add examples). | |
| - Clarify code comments, improve variable names, or refactor code. | |
| - Add test coverage for untested areas. | |
| - Help triage issues (identify duplicates, provide additional context). |
|
|
||
| ## Your First Contribution | ||
| ### Find Something to Work On | ||
| The first step in contributing to AsyncAPI is identifying an issue to work on. Contributions come in many forms, and every contribution, big or small, matters! Here are a few ways to get started: |
There was a problem hiding this comment.
| The first step in contributing to AsyncAPI is identifying an issue to work on. Contributions come in many forms, and every contribution, big or small, matters! Here are a few ways to get started: | |
| The first step in contributing to AsyncAPI is identifying an issue to work on. Contributions come in many forms, and every contribution, big or small, matters. Here are a few ways to get started: |
|
|
||
| - Help triage issues (identify duplicates, provide additional context). | ||
|
|
||
| If none of the above resonate with you, check out issues labeled `"good first issue"` or `"help wanted"` in the repositories. These labels indicate tasks that are well-scoped for new contributors. |
There was a problem hiding this comment.
| If none of the above resonate with you, check out issues labeled `"good first issue"` or `"help wanted"` in the repositories. These labels indicate tasks that are well-scoped for new contributors. | |
| If none of the above resonates with you, check out issues labeled `good first issue` or `help wanted` in the repositories. These labels indicate tasks that are well-scoped for new contributors. |
|
|
||
| If none of the above resonate with you, check out issues labeled `"good first issue"` or `"help wanted"` in the repositories. These labels indicate tasks that are well-scoped for new contributors. | ||
|
|
||
| >⚠ Note: While all contributions are welcome, each pull request requires review and testing from maintainers. Please avoid unnecessary PRs (like fixing minor linter warnings, single-character typos or reformatting) unless they add real value. Always communicate with maintainers before making such changes. |
There was a problem hiding this comment.
Please delete this note as it sounds contradictory and the definition of "adds real value" is extremely subjective and can potentially trigger a lot of confusion and misunderstanding.
- fixing minor linter warnings - does it make sense to fix it when it will remove 5 warnings from the console? And what about 20 or 50?
- single-character typos - documentation in any form must be error-free. Period. Otherwise it indicates poor quality, potentially triggers confusion and misunderstanding due to erroneous instructions.
- reformatting - if you can express something more clearly, unambiguously, and even using fewer words, why wouldn't you do it?
|
|
||
|
|
||
| ## How to Find Good First Issues | ||
| Imagine you're a detective searching for clues. In open-source, your clues are GitHub issues— tasks that need solving. Some issues are complex mysteries, while others are simple puzzles that are perfect for beginners. |
There was a problem hiding this comment.
| Imagine you're a detective searching for clues. In open-source, your clues are GitHub issues— tasks that need solving. Some issues are complex mysteries, while others are simple puzzles that are perfect for beginners. | |
| Imagine you're a detective searching for clues. In open-source, your clues are GitHub issues - tasks that need solving. Some issues are complex mysteries, while others are simple puzzles that are perfect for beginners. |
| This is like a video game where "Good First Issues" are Level 1 quests— easy enough for beginners but still important for the game progression! | ||
|
|
||
| ### Understanding Issue Labels | ||
| When looking at issues, you might see different labels. Here’s what they mean: |
There was a problem hiding this comment.
| When looking at issues, you might see different labels. Here’s what they mean: | |
| When looking at issues, you might see different labels. Here's what they mean: |
| |---------------------|-----------------------------------------------| | ||
| | **good first issue** | Great for newcomers! Clearly defined and simple. | | ||
| | **help wanted** | Extra attention is needed, may require some research. | | ||
| | **bug** | Something isn't working correctly—time to fix it!| |
There was a problem hiding this comment.
| | **bug** | Something isn't working correctly—time to fix it!| | |
| | **bug** | Something isn't working correctly, so it's time to fix it!| |
| | **gsod** | Google Season of Docs-related ideas/issues. | | ||
| | **Hacktoberfest** | Available for Hacktoberfest participants. | | ||
| | **dependencies** | Pull requests that update dependencies. | | ||
| | **do-not-merge** | Indicates PRs that shouldn't be merged.| |
There was a problem hiding this comment.
What are possible use cases here?
There was a problem hiding this comment.
GSoD is not happening anymore so I've removed that. Remaining ones I've collected from repos where hacktoberfest issues are created. My idea was to give a brief description of how can a beginner know which issue label means what as labels might differ from org to org.
| AsyncAPI follows a "first come, first served" approach for issue assignment: | ||
|
|
||
| - Comment on the issue – Start with saying something like, "Hey, I’d like to work on this!" so maintainers know you're interested. | ||
| - We do not pre-assign issues. Instead, contributors must comment on an issue they want to work on. | ||
| - Once you comment, wait for approval by maintainers. They may guide you further (if needed) or might assign the issue to you. If there are no blockers, you can start working! | ||
| - Start coding! – Once approved, fork the repository, create a new branch, and start working! | ||
| - Ask for help – Don’t hesitate to ask in the issue comments or the dedicated AsyncAPI Slack Channel if you’re stuck. |
There was a problem hiding this comment.
@CBID2 On line 92, I would suggest linking to the Git Workflow document as it contains instructions specific to AsyncAPI instead of generic ones.
| - Start coding! – Once approved, fork the repository, create a new branch, and start working! | ||
| - Ask for help – Don’t hesitate to ask in the issue comments or the dedicated AsyncAPI Slack Channel if you’re stuck. | ||
|
|
||
| So what are you waiting for? Go find your first quest, and let’s build something awesome together! |
There was a problem hiding this comment.
| So what are you waiting for? Go find your first quest, and let’s build something awesome together! | |
| So what are you waiting for? Go find your first quest, and let's build something awesome together! |
|
@SaxenaAnushka102 Please don't mix different topics in one PR - remove the |
|
@SaxenaAnushka102 any progress? |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/onboarding-guide/identifying-good-first-issues.md (1)
27-27: Refine section headingThis H3 closely mirrors the earlier “How to Find Good First Issues” section and has a trailing colon. Consider renaming it for clarity and removing the colon:
-### How to Find These Issues: +### Locate Issues in the UI🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
27-27: Trailing punctuation in heading
Punctuation: ':'(MD026, no-trailing-punctuation)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/onboarding-guide/identifying-good-first-issues.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/onboarding-guide/identifying-good-first-issues.md
[grammar] ~11-~11: Did you mean the verb “finds”?
Context: ...yncAPI. ## Your First Contribution ### Find Something to Work On The first step in ...
(SENT_START_PRPS_JJ_NN_VBP)
[style] ~89-~89: Using many exclamation marks might seem excessive (in this case: 7 exclamation marks for a text that’s 4527 characters long)
Context: ...d let’s build something awesome together!
(EN_EXCESSIVE_EXCLAMATION)
🪛 markdownlint-cli2 (0.17.2)
docs/onboarding-guide/identifying-good-first-issues.md
27-27: Trailing punctuation in heading
Punctuation: ':'
(MD026, no-trailing-punctuation)
🔇 Additional comments (3)
docs/onboarding-guide/identifying-good-first-issues.md (3)
1-5: Verify front matter fields per docs requirementsThe front matter currently includes
title,description, andweight, but omitsidandsidebar_labelwhich some Docusaurus‐based configs may require. Please confirm with the AsyncAPI docs guidelines whether you need to addidandsidebar_labelor if this minimal front matter is sufficient.
4-4: Confirmweightplacement in documentation orderingYou've set
weight: 50—ensure this value places the guide in the intended position within the sidebar relative to other onboarding docs.
52-77: Verify issue labels table against current labelsPlease cross-check this table against the actual labels used across AsyncAPI repositories to ensure accuracy in both label names (e.g.,
docs bugvsdocs-bug) and descriptions. Mismatches here could confuse new contributors.
| - Add test coverage for untested areas. | ||
| - Help triage issues (identify duplicates, provide additional context). | ||
| ## How to Find Good First Issues | ||
| Imagine you're a detective searching for clues. In open-source, your clues are GitHub issues- tasks that need to be solved. Some issues are complex mysteries, while others are simple puzzles that are perfect for beginners. |
There was a problem hiding this comment.
| Imagine you're a detective searching for clues. In open-source, your clues are GitHub issues- tasks that need to be solved. Some issues are complex mysteries, while others are simple puzzles that are perfect for beginners. | |
| Imagine you're a detective searching for clues. In open-source, your clues are GitHub issues - tasks that need to be solved. Some issues are complex mysteries, while others are simple puzzles that are perfect for beginners. |
| - `good first issue` – These are beginner-friendly and usually come with clear instructions. | ||
| - `help wanted` – These issues need attention, but may require a bit more effort. |
| - `good first issue` – These are beginner-friendly and usually come with clear instructions. | ||
| - `help wanted` – These issues need attention, but may require a bit more effort. | ||
|
|
||
| ### How to Find These Issues: |
|
@SaxenaAnushka102 Please be more attentive to the suggestions. I see many of them are skipped (or ignored) @thulieblack FYI ^^ |
|
@SaxenaAnushka102 please address the pending reviews |
|
@bandantonio I didn't mean to ignore or skip the suggestions. I'm not sure why the changes I make directly from recommendations in comments aren't reflecting in my PR. Apologies, I'll fix this ASAP. |
|
I'm on it, @thulieblack !🫡 |
|
When implementing your review changes always open the |
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
docs/onboarding-guide/identifying-good-first-issues.md (2)
1-5:⚠️ Potential issueAdd missing front matter fields
The guide is missingidandsidebar_labelin its front matter, which are required by the AsyncAPI docs site.Apply this diff:
--- + id: identifying-good-first-issues title: Identifying Good First Issues description: A guide to help new contributors find and work on beginner-friendly issues in AsyncAPI projects + sidebar_label: Identifying Good First Issues weight: 50 ---
7-7:⚠️ Potential issueAlign the main heading with the document title
The H1 heading doesn’t match the guide’s focus and front matter title.Change it to:
-# Start Contributing to AsyncAPI +# Identifying Good First Issues
🧹 Nitpick comments (3)
docs/onboarding-guide/identifying-good-first-issues.md (3)
23-25: Add a missing comma
Insert a comma before “but” for clarity.-These issues can have detailed instructions as well but may require more extensive implementation effort. +These issues can have detailed instructions as well, but may require more extensive implementation effort.🧰 Tools
🪛 LanguageTool
[uncategorized] ~25-~25: Possible missing comma found.
Context: ...s can have detailed instructions as well but may require more extensive implementati...(AI_HYDRA_LEO_MISSING_COMMA)
37-39: Clarify step 3 instructions using GitHub filters
Rather than leaving it open-ended, show newcomers how to use the UI filters.-3. Use the search bar or label filters to locate issues labeled like: `good first issue` or `help wanted`. +3. Click on the **Filters** button, select **Label**, then choose `good first issue` and/or `help wanted` to narrow down beginner-friendly tasks.
85-86: Tone down exclamation
Consider reducing or removing the final exclamation to maintain a professional tone.-So what are you waiting for? Go find your first quest, and let's build something awesome together! +So what are you waiting for? Go find your first quest, and let's build something awesome together.🧰 Tools
🪛 LanguageTool
[style] ~85-~85: Using many exclamation marks might seem excessive (in this case: 7 exclamation marks for a text that’s 4622 characters long)
Context: ...d let's build something awesome together!(EN_EXCESSIVE_EXCLAMATION)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/onboarding-guide/identifying-good-first-issues.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/onboarding-guide/identifying-good-first-issues.md
[grammar] ~11-~11: Did you mean the verb “finds”?
Context: ...yncAPI. ## Your First Contribution ### Find Something to Work On The first step in ...
(SENT_START_PRPS_JJ_NN_VBP)
[uncategorized] ~25-~25: Possible missing comma found.
Context: ...s can have detailed instructions as well but may require more extensive implementati...
(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~85-~85: Using many exclamation marks might seem excessive (in this case: 7 exclamation marks for a text that’s 4622 characters long)
Context: ...d let's build something awesome together!
(EN_EXCESSIVE_EXCLAMATION)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Test NodeJS PR - windows-latest
| | **good first issue** | Great for newcomers! Clearly defined and simple. | | ||
| | **help wanted** | Extra attention is needed, may require some research. | |
There was a problem hiding this comment.
Lines 22-25, 43, 50-51 repeat the same information over and over again
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
docs/onboarding-guide/identifying-good-first-issues.md (1)
7-7: 🛠️ Refactor suggestionH1 heading should match front matter title
Please update the main heading to align with thetitlein front matter.-# Start Contributing to AsyncAPI +# Identifying Good First Issues
🧹 Nitpick comments (2)
docs/onboarding-guide/identifying-good-first-issues.md (2)
42-67: Consider organizing the label table
The table is comprehensive, but grouping labels by category or sorting alphabetically could improve scanability.
79-79: Tone down exclamation marks
Reducing excessive punctuation will lend a more professional tone.-So what are you waiting for? Go find your first quest, and let's build something awesome together! +So what are you waiting for? Go find your first quest, and let's build something awesome together.🧰 Tools
🪛 LanguageTool
[style] ~79-~79: Using many exclamation marks might seem excessive (in this case: 7 exclamation marks for a text that’s 4219 characters long)
Context: ...d let's build something awesome together!(EN_EXCESSIVE_EXCLAMATION)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/onboarding-guide/identifying-good-first-issues.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/onboarding-guide/identifying-good-first-issues.md
[grammar] ~11-~11: Did you mean the verb “finds”?
Context: ...yncAPI. ## Your First Contribution ### Find Something to Work On The first step in ...
(SENT_START_PRPS_JJ_NN_VBP)
[style] ~79-~79: Using many exclamation marks might seem excessive (in this case: 7 exclamation marks for a text that’s 4219 characters long)
Context: ...d let's build something awesome together!
(EN_EXCESSIVE_EXCLAMATION)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Test NodeJS PR - windows-latest
🔇 Additional comments (5)
docs/onboarding-guide/identifying-good-first-issues.md (5)
1-5: Front matter meets requirements
The YAML block includestitle,description, andweightand adheres to AsyncAPI docs conventions.
8-9: Intro is clear and welcoming
Great job setting the stage and motivating new contributors.
14-17: Contribution examples are well-scoped
The list of beginner-friendly tasks is concise and actionable.
19-19: Effective analogy
The detective metaphor makes the concept of issue hunting approachable.
26-38: Step-by-step guidance is solid
Screenshots paired with instructions will help newcomers navigate GitHub with confidence.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (7)
docs/onboarding-guide/identifying-good-first-issues.md (7)
8-9: Simplify the introductory tone
Consider reducing rhetorical questions to improve clarity (e.g., remove or rephrase “Not sure where to make your first contribution?”).
10-17: Flatten heading structure
Since “Find Something to Work On” is the only subsection under “Your First Contribution,” you could drop the H2 “Your First Contribution” and bump that content to H2 for a more streamlined hierarchy.🧰 Tools
🪛 LanguageTool
[grammar] ~11-~11: Did you mean the verb “finds”?
Context: ...yncAPI. ## Your First Contribution ### Find Something to Work On The first step in ...(SENT_START_PRPS_JJ_NN_VBP)
18-23: Markdown heading and phrasing
Insert a blank line before the H2 at line 18 to ensure proper rendering, and consider rephrasing “If none of the above resonates with you” to something more direct (e.g., “Alternatively, search by label…”).
24-38: Improve screenshot alt text and wording
- Use descriptive alt text for images (e.g., “AsyncAPI organization page screenshot”).
- Change “labeled like:
good first issueorhelp wanted” to “labeledgood first issueorhelp wanted” for tighter wording.
39-67: Trim or reorganize the labels table
This list is extensive—consider grouping related labels (e.g.,area/*labels into one section), ordering alphabetically, or removing less-common entries to improve scannability.
69-79: Adjust heading level and link text
- Change “### Next Steps” to “## Next Steps” to match top-level sections.
- Capitalize the link text to “[Git Workflow Guide]” for consistency with other docs.
🧰 Tools
🪛 LanguageTool
[style] ~79-~79: Using many exclamation marks might seem excessive (in this case: 7 exclamation marks for a text that’s 4218 characters long)
Context: ...d let's build something awesome together!(EN_EXCESSIVE_EXCLAMATION)
80-80: Tone down the closing emphasis
Consider reducing or removing the exclamation mark in the final sentence to maintain a professional tone.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/onboarding-guide/identifying-good-first-issues.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/onboarding-guide/identifying-good-first-issues.md
[grammar] ~11-~11: Did you mean the verb “finds”?
Context: ...yncAPI. ## Your First Contribution ### Find Something to Work On The first step in ...
(SENT_START_PRPS_JJ_NN_VBP)
[style] ~79-~79: Using many exclamation marks might seem excessive (in this case: 7 exclamation marks for a text that’s 4218 characters long)
Context: ...d let's build something awesome together!
(EN_EXCESSIVE_EXCLAMATION)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Test NodeJS PR - windows-latest
🔇 Additional comments (2)
docs/onboarding-guide/identifying-good-first-issues.md (2)
7-7: H1 matches the document title
Looks good.
1-5:❌ Incorrect review comment
Ensure required front matter fields
Addsidebar_label: Identifying Good First Issues(and, if needed, anid) to align with AsyncAPI docs guidelines and maintain consistency with other guides.
🏁 Script executed:
#!/bin/bash # List all occurrences of sidebar_label in documentation rg -n 'sidebar_label:' docs # List all occurrences of id in front matter across docs rg -n '^id:' docsLength of output: 47
Ignore Front Matter Sidebar Label Suggestion
I checked the rest ofdocs/and didn’t find any existing pages usingsidebar_labeloridin their front matter. Since none of the other guides include these fields and the site builds correctly without them, this change isn’t needed.Likely an incorrect or invalid review comment.
Description
Related issue(s)
See also #1622
Summary by CodeRabbit