Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add onboarding code contributor guide #1725

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

docs: add onboarding code contributor guide #1725

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7185f88
Create code-contributor-guide.md
SaxenaAnushka102 Feb 16, 2025
0a4a9e6
Update docs/onboarding-guide/code-contributor-guide.md
SaxenaAnushka102 Feb 22, 2025
26375e4
Merge branch 'master' into onboarding-code-contributor-guide
thulieblack Feb 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 79 additions & 0 deletions docs/onboarding-guide/code-contributor-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# AsyncAPI Onboarding Code Contributor Guide

Welcome to the AsyncAPI community! We’re excited to have you here. Think of AsyncAPI as a collaborative puzzle—your contributions are essential to completing it. This guide will help you get started smoothly.

---
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would rather remove these lines everywhere, as they are not consistent (there is no line before the last h2 heading) and also add visual noise

Suggested change
---


## Understanding AsyncAPI
[AsyncAPI](https://www.asyncapi.com/en) is an open-source initiative for defining and building event-driven architectures. Our repositories house tools, specifications, and generators that make event-driven systems easier to work with. Each repo has a purpose, detailed in its `README.md`.

---

## 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically speaking, VS Code is not an IDE, it's a code editor

Screenshot 2025-02-20 at 9 56 02 PM
Suggested change
- **Code Editor**: Your favourite IDEs like VS Code.
- **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, so ensure these are installed and configured.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.


---

## Contribution Etiquette
1. Follow the [Code of Conduct](https://github.com/asyncapi/community/blob/master/CODE_OF_CONDUCT.md)
2. Stick to the [Contributing guidelines](https://github.com/asyncapi/community/blob/master/CONTRIBUTING.md)
3. Document Everything
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wish we could make it true 😁 Never stop dreaming :)

I believe, the idea behind this point is to "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

---

## Branch Strategy
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## Branch Strategy
## Contribution Strategy

AsyncAPI uses a "Fork and Pull" workflow. In Git terms:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This part is a bit too technical with terms and may be unclear for some newcomers who are not fully proficient with git yet. I suggest rewriting it using a more descriptive style. For example:

Suggested change
AsyncAPI uses a "Fork and Pull" workflow. In Git terms:
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`.

- Your **fork** is the `origin`.
- The official AsyncAPI repository is the `upstream`.
Comment on lines +35 to +36
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can be deleted


### Adding Upstream
Add the `upstream` repository and prevent pushing directly to it:

```bash
# Replace <upstream git repo> with the AsyncAPI repo URL
# Example:
# https://github.com/asyncapi/generator.git
# git@github.com:asyncapi/generator.git

git remote add upstream <upstream git repo>
git remote set-url --push upstream no_push
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
```
Comment on lines +51 to +54
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 -v

Example output:

origin  https://github.com/<username>/generator.git (fetch)
origin  https://github.com/<username>/generator.git (push)
upstream        git@github.com:asyncapi/generator.git (fetch)
upstream        git@github.com:asyncapi/generator.git (push)


### Keeping Your Fork in Sync
Before starting new work, sync your fork with the upstream:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Before starting new work, sync your fork with the upstream:
Before starting new work, sync your `origin` with the `upstream`:


```bash
git fetch upstream
git checkout master # Use 'main' if that's the default branch
git rebase upstream/master
git push
```

### Starting a New Branch
Create a feature branch for your contribution:

```bash
git checkout -b myfeature
```

## Submitting Your First Pull Request
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section tells nothing about how to actually submit a pull request from origin to upstream

- Fork and Clone: Fork the repository and clone it locally.
- Branch Off: Create a new branch for your work.
- Commit Changes: Write clear and concise commit messages.
- Push and PR: Push your branch and open a pull request.

Every contribution matters, no matter how small. Dive in and let’s build something amazing together!