docs: add onboarding code contributor guide #1725
Conversation
SaxenaAnushka102
requested review from
quetzalliwrites,
derberg,
asyncapi-bot-eve and
thulieblack
as code owners
| ## Tools You’ll Need | ||
| - **Git and GitHub**: Your tools for collaboration. Get familiar with forking, branching, and pull requests. | ||
| - **Code Editor**: Your favourite IDEs like VS Code. | ||
| - **Node.js & NPM**: AsyncAPI relies on JavaScript, so ensure these are installed and configured. |
There was a problem hiding this comment.
| - **Node.js & NPM**: AsyncAPI relies on JavaScript, so ensure these are installed and configured. | |
| - **Node.js and npm**: AsyncAPI relies on JavaScript/TypeScript, so ensure these are installed and configured. |
|
|
||
| ## Starting Small | ||
| - Look for `good first issue` or `help wanted` labels in the repository. These are beginner-friendly issues to get you started. | ||
| - Join our [Slack workspace](https://t.co/YbJQ4ghX7Q) for help and to connect with the community. |
There was a problem hiding this comment.
@thulieblack just a thought: I remember one of our Mentorship meetings, where you said that dedicated Slack channels act as your target audience, mentors, tutors, so you should use them to get as much feedback as possible and don't be afraid to ask questions, as someone said "The only stupid question is the one that is not asked".
I think it's worth adding this info to slack-etiquette because I bet that "what and how to ask in channels" is a common stumbling stone for newcomers.
| - Your **fork** is the `origin`. | ||
| - The official AsyncAPI repository is the `upstream`. |
| # [email protected]:asyncapi/generator.git | ||
|
|
||
| git remote add upstream <upstream git repo> | ||
| git remote set-url --push upstream no_push |
There was a problem hiding this comment.
Are you sure that this step is required? If I'm not mistaken, regular contributors will receive the standard Permission denied error when trying to push to upstream directly.
| ### Verify with: | ||
| ```bash | ||
| git remote -v | ||
| ``` |
There was a problem hiding this comment.
You showed an example above, so I think it would be useful for newcomers to see example output of this command as well. Or even better, show output of git remote -v before adding upstream, and after.
Verify that upstream has been set:
git remote -vExample output:
origin https://github.com/<username>/generator.git (fetch)
origin https://github.com/<username>/generator.git (push)
upstream [email protected]:asyncapi/generator.git (fetch)
upstream [email protected]:asyncapi/generator.git (push)| ``` | ||
|
|
||
| ### Keeping Your Fork in Sync | ||
| Before starting new work, sync your fork with the upstream: |
There was a problem hiding this comment.
| Before starting new work, sync your fork with the upstream: | |
| Before starting new work, sync your `origin` with the `upstream`: |
| git checkout -b myfeature | ||
| ``` | ||
|
|
||
| ## Submitting Your First Pull Request |
There was a problem hiding this comment.
This section tells nothing about how to actually submit a pull request from origin to upstream
|
@SaxenaAnushka102 any update here |
Hi @thulieblack @bandantonio ! I've incorporated the suggested changes in the latest commit. Please have a look and let me know your thoughts on this, thanks! |
|
|
||
| --- | ||
| - **Code Editor**: Your tool to work with the source code of our repositories and version control. For example, VS Code, Sublime Text, JetBrains IDEs, or any other tool you prefer. | ||
| - **Node.js & NPM**: AsyncAPI relies on JavaScript/Typescript, so ensure these are installed and configured. |
| ``` | ||
| Replace `my-feature-branch` with a meaningful branch name (e.g., `fix-tests`). | ||
|
|
||
| ### **2. Make Changes and Commit** |
There was a problem hiding this comment.
I would split this step into three because all of them are logically separate operations:
- Make changes
- Commit
- Push
|
|
||
| ## Submitting Your First Pull Request (PR) | ||
|
|
||
| Once you've made changes to your forked repository, you need to submit a **Pull Request (PR)** to propose merging your work into the official AsyncAPI repository. Follow these steps: |
There was a problem hiding this comment.
The section is logically incoherent.
Once you've made changes to your forked repository, you need to submit a Pull Request (PR)
You cannot submit a PR at this point, because you haven't pushed the changes to the repo yet.
The push step must be a part of the previous section as the logical conclusion of working with changes locally.
The "creating a PR" part is continuation of the process when you're most likely working with GitHub UI to create it, so the additional back and forth step of going back to your IDE in order to push the changes is irrelevant here, as it adds unnecessary noise and looks confusing.
|
|
||
| --- | ||
| ## Contribution Strategy |
There was a problem hiding this comment.
Please remove this section as we agreed not to duplicate these instructions to keep the git-workflow (PR #1772) a single source of truth.
|
|
||
| ### Making Code Changes | ||
|
|
||
| AsyncAPI uses a fork model to allow contributions to the organization's repositories. In this model, you push changes to your own working copy (a fork, a so-called `origin`) of the official repository (a so-called `upstream`), and then create a pull request (PR) to incorporate changes from the `origin` to `upstream`. For detailed steps, refer to our [Git Workflow Guide](https://github.com/asyncapi/community/blob/master/git-workflow.md). |
There was a problem hiding this comment.
I used the similar phrasing in my git-workflow PR.
I would suggest rephrasing (or better removing) this intro (to avoid duplication and potential confusion and misunderstanding among new contributors) and link to the corresponding section of the git-workflow file.
There was a problem hiding this comment.
Alright, got your point. Sorry for the confusion on the same thing again. Shall we remove the whole paragraph or omit the section to directly start from the steps (creating a new branch being the first)? My thought behind adding the link was to point the new contributors to the ideal git-workflow and explain how they can actually make changes to code.
There was a problem hiding this comment.
What do you think about creating the "Prerequisites" section and adding links to Git workflow and Recommended tools documents there? Because the "Tools You’ll Need" section 100% overlaps with the #1777 PR. Again, it's better to have a single place where you describe things rather than being forced to update a myriad of documents once something changes.
There was a problem hiding this comment.
I agree, there's multiple repetition of same points but in the prerequisites the code contributor should again have knowledge of git, have code editor and so on. To resolve this redundancy issue, shall we directly put link to recommended tools and git workflow here?
There was a problem hiding this comment.
@SaxenaAnushka102 Didn't quite catch your idea. I believe, if we add a new section called "Prerequisites" after "Understanding AsyncAPI" that would contain links to the updated git workflow and recommended tools based on #1777 PR, we will have no redundancy (you will need to remove the "Making Code Changes" section as well). Does this answer your question?
There was a problem hiding this comment.
@SaxenaAnushka102 still not implemented
There was a problem hiding this comment.
Apologies, I missed this comment.
|
|
||
| AsyncAPI uses a fork model to allow contributions to the organization's repositories. In this model, you push changes to your own working copy (a fork, a so-called `origin`) of the official repository (a so-called `upstream`), and then create a pull request (PR) to incorporate changes from the `origin` to `upstream`. For detailed steps, refer to our [Git Workflow Guide](https://github.com/asyncapi/community/blob/master/git-workflow.md). | ||
|
|
||
| ### **1. Creating a New Branch** |
Signed-off-by: Anushka Saxena <[email protected]>
| @@ -0,0 +1,80 @@ | |||
| --- | |||
| title: Code Contributor Guide | |||
There was a problem hiding this comment.
Add a description to your page
| ## Tools You’ll Need | ||
| - Git and GitHub: Your tools for collaboration. Get familiar with forking, branching, and pull requests. | ||
| - Code Editor: Your tool to work with the source code of our repositories and version control. For example, VS Code, Sublime Text, JetBrains IDEs, or any other tool you prefer. | ||
| - Node.js & npm: AsyncAPI relies on JavaScript/Typescript, so ensure these are installed and configured. |
There was a problem hiding this comment.
| - Node.js & npm: AsyncAPI relies on JavaScript/Typescript, so ensure these are installed and configured. | |
| - Node.js & npm: AsyncAPI relies on JavaScript/TypeScript, so ensure these are installed and configured. |
WalkthroughA new documentation file, "Code Contributor Guide," has been added to the onboarding section. This guide provides step-by-step instructions for new contributors to the AsyncAPI project, covering the tools required, contribution etiquette, the fork-and-branch workflow, pull request procedures, and the review and merge process. The document is structured to help new contributors understand the process of contributing code, including example commands and guidance on communication and documentation standards. Changes
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:
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
🔭 Outside diff range comments (1)
docs/onboarding-guide/code-contributor-guide.md (1)
81-82:⚠️ Potential issueRemove stray line number or extra whitespace
Line 82 appears to be a stray number without content. Please remove it or confirm if it's an unintended artifact.
♻️ Duplicate comments (3)
docs/onboarding-guide/code-contributor-guide.md (3)
18-23: Augment communication etiquette with Slack guidelines
Great coverage of contribution etiquette—consider adding a reference to the Slack Etiquette guide to help newcomers ask questions effectively in community channels.
13-17: 🛠️ Refactor suggestionAvoid duplication; link to central 'Recommended Tools' guide
The list of required tools overlaps with the Recommended Tools document. Consider replacing this section with a brief note and a link to keep tooling instructions in a single source of truth.
24-27: 🛠️ Refactor suggestionReorganize workflow introduction into 'Prerequisites'
To streamline onboarding, introduce a "Prerequisites" section after "Understanding AsyncAPI" linking to both the Git Workflow and Recommended Tools guides. Then rename or remove the "Making Code Changes" paragraph to reduce redundancy.
🧹 Nitpick comments (6)
docs/onboarding-guide/code-contributor-guide.md (6)
1-5: Verify frontmatter consistency and metadata
Ensuretitle,description, andweightalign with other onboarding guides for consistent ordering and display. Consider adding asidebar_labelorslugif the autogenerated sidebar label needs customization.
6-9: Refine introduction and trailing whitespace
Remove excessive trailing spaces on line 8 and ensure a single blank line before the next heading. Consider tightening the welcome message or simplifying the analogy for clarity.
10-12: Enhance clarity of 'Understanding AsyncAPI' description
Rephrase "Each repo has a purpose, detailed in itsREADME.md." to "Each repository contains tools and details in itsREADME.md." for improved readability.🧰 Tools
🪛 LanguageTool
[duplication] ~10-~10: Possible typo: you repeated a word.
Context: ...t started smoothly. ## Understanding AsyncAPI AsyncAPI is an ope...(ENGLISH_WORD_REPEAT_RULE)
28-33: Clarify branch naming conventions
Consider adding guidance on branch naming schemes (e.g.,feat/<scope>-<description>orfix/<issue-number>-<description>) to align with Conventional Commits and repository standards.
61-64: Use consistent imperative tone
For alignment with UI copy standards, consider rewriting to an imperative voice, e.g., "Create your first Pull Request" rather than "Once you've pushed your changes, you need to create...".
65-73: Generalize repository placeholders
Replace hardcodedgeneratorin the URL example with a placeholder like<repository>so that contributors can adapt this to any AsyncAPI repo (e.g., generator, parser, etc.).
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/onboarding-guide/code-contributor-guide.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/onboarding-guide/code-contributor-guide.md
[duplication] ~10-~10: Possible typo: you repeated a word.
Context: ...t started smoothly. ## Understanding AsyncAPI AsyncAPI is an ope...
(ENGLISH_WORD_REPEAT_RULE)
🔇 Additional comments (3)
docs/onboarding-guide/code-contributor-guide.md (3)
36-38: Step is clear and concise
This instruction to make changes is straightforward and easy to follow.
54-59: Push step is correctly described
The instructions to push changes to the origin branch are complete and clear.
76-80: Approve final steps and encouragement
The review & merge process and closing encouragement are well written and motivating for new contributors.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
docs/onboarding-guide/code-contributor-guide.md (4)
8-8: Remove unnecessary trailing whitespace.
The two spaces after "smoothly." produce a hard line break but may introduce trailing whitespace noise. Consider removing them unless a manual break is intentional.
13-17: Link to a centralized "Recommended Tools" document.
The "Tools You’ll Need" section duplicates content from your existing tools guide. To keep documentation DRY and ensure a single source of truth, consider replacing this list with a concise pointer to the canonical tools page.Example diff:
- ## Tools You’ll Need - - Git and GitHub: Your tools for collaboration. Get familiar with forking, branching, and pull requests. - - Code Editor: Your tool to work with the source code of our repositories and version control. For example, VS Code, Sublime Text, JetBrains IDEs, or any other tool you prefer. - - Node.js & npm: AsyncAPI relies on JavaScript/TypeScript, so ensure these are installed and configured. + ## Prerequisites + For a recommended development environment—including Git, code editors, Node.js, and npm—see our [Recommended Tools guide](https://github.com/asyncapi/community/blob/master/recommended-tools.md).
22-22: Add hyperlink to Slack Etiquette.
You mention "designated Slack channels" under Contribution Etiquette. It would help newcomers to link directly to the Slack Etiquette document for guidance on asking questions and interacting appropriately.
26-27: Consolidate or rename "Making Code Changes".
The fork-model overview overlaps substantially with the more detailed Git Workflow Guide. You could rename this section (e.g., "Getting Started with Git") and link out, or trim it to a brief summary before deferring to the Git Workflow Guide.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/onboarding-guide/code-contributor-guide.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/onboarding-guide/code-contributor-guide.md
[duplication] ~10-~10: Possible typo: you repeated a word.
Context: ...t started smoothly. ## Understanding AsyncAPI AsyncAPI is an ope...
(ENGLISH_WORD_REPEAT_RULE)
🔇 Additional comments (1)
docs/onboarding-guide/code-contributor-guide.md (1)
1-5: Verify front matter completeness and ordering.
Please confirm that theweight: 90value correctly positions this guide within the onboarding section and that no additional fields (e.g.,slug,tags) are required by your Docs site configuration.
|
@SaxenaAnushka102 any update |
|
Hi @thulieblack! I've made the changes that were requested in previous review iteration. If there are no further changes required, I think we're good to go with this. Thanks! |
|
|
||
| AsyncAPI uses a fork model to allow contributions to the organization's repositories. In this model, you push changes to your own working copy (a fork, a so-called `origin`) of the official repository (a so-called `upstream`), and then create a pull request (PR) to incorporate changes from the `origin` to `upstream`. For detailed steps, refer to our [Git Workflow Guide](https://github.com/asyncapi/community/blob/master/git-workflow.md). | ||
|
|
||
| ### 1. Creating a New Branch |
There was a problem hiding this comment.
| ### 1. Creating a New Branch | |
| ### 1. Create a New Branch |
| git push origin my-feature-branch | ||
| ``` | ||
|
|
||
| ## Submitting Your First Pull Request (PR) |
There was a problem hiding this comment.
| ## Submitting Your First Pull Request (PR) | |
| ## Submit Your First Pull Request (PR) |
| 3. Document the "why" of your contribution(s). Make sure that someone who opens the code for the first time understands the changes you've made. | ||
| 4. Communicate openly through discussions on GitHub or designated Slack channels. | ||
|
|
||
| ### Making Code Changes |
There was a problem hiding this comment.
| ### Making Code Changes | |
| ### Make Code Changes |
|
|
||
| ### Making Code Changes | ||
|
|
||
| AsyncAPI uses a fork model to allow contributions to the organization's repositories. In this model, you push changes to your own working copy (a fork, a so-called `origin`) of the official repository (a so-called `upstream`), and then create a pull request (PR) to incorporate changes from the `origin` to `upstream`. For detailed steps, refer to our [Git Workflow Guide](https://github.com/asyncapi/community/blob/master/git-workflow.md). |
There was a problem hiding this comment.
@SaxenaAnushka102 still not implemented
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
docs/onboarding-guide/code-contributor-guide.md (2)
6-6: Remove trailing whitespace on title heading
There are extra spaces at the end of the title line which may introduce an unintended line break. Please trim them.
31-39: Align subheading style with numbered steps
Under “Submit Your First Pull Request (PR)”, rename the “### Create a Pull Request (PR)” subheading to “### 1. Create a Pull Request” so it aligns visually with the numbered workflow in this section.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/onboarding-guide/code-contributor-guide.md(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📓 Common learnings
Learnt from: thulieblack
PR: asyncapi/community#1730
File: docs/onboarding-guide/contribution-flow.md:1-4
Timestamp: 2025-04-29T11:49:47.903Z
Learning: In the asyncapi/community repository, `docs/onboarding-guide/contribution-flow.md` is the correct path for contribution flow documentation, not `docs/community/onboarding-guide/contribution-flow.md`.
🪛 LanguageTool
docs/onboarding-guide/code-contributor-guide.md
[duplication] ~10-~10: Possible typo: you repeated a word.
Context: ...t started smoothly. ## Understanding AsyncAPI AsyncAPI is an ope...
(ENGLISH_WORD_REPEAT_RULE)
🔇 Additional comments (6)
docs/onboarding-guide/code-contributor-guide.md (6)
1-5: Verify frontmatter metadata
The YAML frontmatter looks well-formed. Please confirm thatweight: 90places this guide in the correct order alongside other onboarding docs.
8-9: Engaging introduction!
The welcome message and the puzzle analogy are clear and inviting for new contributors. Great job!
10-12: Good overview of AsyncAPI
This section concisely explains what AsyncAPI is and links to each repo’s README for more detail.🧰 Tools
🪛 LanguageTool
[duplication] ~10-~10: Possible typo: you repeated a word.
Context: ...t started smoothly. ## Understanding AsyncAPI AsyncAPI is an ope...(ENGLISH_WORD_REPEAT_RULE)
21-26: Solid contribution etiquette section
The list of Code of Conduct, contributing guidelines, documenting “why,” and communication tips is well structured and easy to follow.
42-46: Clear review & merge instructions
This section succinctly describes what happens after submission and sets expectations for contributors.
47-47: Motivational closing statement
Strong call-to-action—this encouragement will leave new contributors feeling welcome.
| ## Prerequisites | ||
| Before you begin contributing code, make sure you're familiar with the following: | ||
|
|
||
| - [Git Workflow Guide](https://github.com/asyncapi/community/blob/master/git-workflow.md): Learn how to fork, branch, commit, and open pull requests. | ||
| - [Git](https://git-scm.com) and [GitHub](https://github.com): These are your primary tools for version control and collaboration. Learn the basics [here](https://docs.github.com/en/get-started). | ||
| - Code Editor: Your tool to work with the source code of our repositories and version control. For example, [VS Code](https://code.visualstudio.com), [Sublime Text](https://www.sublimetext.com), [JetBrains IDEs](https://www.jetbrains.com/ides/), or any other tool you prefer. | ||
| - [Node.js & npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm): AsyncAPI relies on JavaScript/TypeScript, so ensure these are installed and configured. | ||
|
|
There was a problem hiding this comment.
💡 Verification agent
🛠️ Refactor suggestion
🧩 Analysis chain
Avoid duplicating “Recommended Tools” content
You list code editors and Node.js/npm here, but we already maintain a central “Recommended Tools” document. Consider linking to that instead to keep a single source of truth and reduce future maintenance.
Would you like assistance drafting that link update?
🏁 Script executed:
#!/bin/bash
# Search for any occurrence of "Recommended Tools" in the docs directory
rg -i -n "Recommended Tools" docs
# List any markdown files with "tools" in their filename
fd '*tools*.md'Length of output: 665
Consolidate “Recommended Tools” content
The contributor guide is duplicating the editor and Node.js/npm recommendations already maintained in docs/onboarding-guide/tools-and-setup.md. To keep one source of truth, please:
- In
docs/onboarding-guide/code-contributor-guide.md(lines 13–20), remove the explicit editor/Node.js bullets. - Add a single link, for example:
See our [Recommended Tools and Setup](../tools-and-setup.md) for editors, Node.js/npm, and other dependencies.
Let me know if you’d like a ready-made diff for this update.
|
@SaxenaAnushka102 Thank you, lgtm |
|
/rtm |
Description
PR related to First project: Onboarding Contributor Guides
Added the Onboarding Code Contributor Guide
Related issue(s)
#1622
Summary by CodeRabbit