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?
|
|
||
| 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
Suggested labels
Suggested reviewers
Poem
Tip ⚡💬 Agentic Chat (Pro Plan, General Availability)
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.
| ### 3. Commit Your Changes | ||
|
|
||
| Check what files you modified: | ||
| ```bash | ||
| git status | ||
| ``` | ||
| Stage the changes: | ||
| ```bash | ||
| git add . | ||
| ``` | ||
| Commit your changes with a meaningful message: | ||
| ```bash | ||
| git commit -m "Fix unit tests" | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Align commit message example with Conventional Commits
The sample commit "Fix unit tests" should follow the Conventional Commits format, e.g., chore(tests): fix unit tests or fix: update unit tests, to reinforce best practices.
Description
PR related to First project: Onboarding Contributor Guides
Added the Onboarding Code Contributor Guide
Related issue(s)
#1622
Summary by CodeRabbit