Skip to content
Merged
Show file tree
Hide file tree
Changes from 18 commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
eb901fb
docs: add section definitions to updated structure
bandantonio Jul 4, 2025
285fc22
docs: update weights for guides in onboarding section
bandantonio Jul 4, 2025
0db8d64
docs: update weights for guides in contribution section
bandantonio Jul 4, 2025
c9bc6b1
docs: update weights for guides in style guide section
bandantonio Jul 5, 2025
7be4b6c
docs: update weights for guides in governance section
bandantonio Jul 5, 2025
52b1b89
docs: update weights for guides in vision and strategy section
bandantonio Jul 5, 2025
4ff3e00
docs: update weights for guides in guides section
bandantonio Jul 5, 2025
3b38dae
docs: update weights for mentorship section
bandantonio Jul 5, 2025
6f2a5ae
docs: update weights for meetings and communication section
bandantonio Jul 5, 2025
cb0e2e4
docs: update weights for marketing section
bandantonio Jul 5, 2025
51671fa
Merge branch 'master' into docs/weights-and-frontmatter
asyncapi-bot Jul 6, 2025
8ccf704
Merge branch 'master' into docs/weights-and-frontmatter
thulieblack Jul 8, 2025
f4003f7
docs: update links to files after structure update (cherry-pick)
bandantonio Jul 6, 2025
df6c4ae
docs: update weights after changing structure
bandantonio Jul 9, 2025
9bdd108
docs: fix linting errors
bandantonio Jul 9, 2025
82a13c9
Merge branch 'master' into docs/weights-and-frontmatter
thulieblack Jul 11, 2025
0994682
Merge branch 'master' into docs/weights-and-frontmatter
thulieblack Jul 15, 2025
1113c67
docs: add index pages to new structure sections
bandantonio Jul 15, 2025
ec4993b
docs: update headings in section index pages
bandantonio Jul 17, 2025
0800409
Merge branch 'master' into docs/weights-and-frontmatter
thulieblack Jul 23, 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
2 changes: 1 addition & 1 deletion docs/000-onboarding/_section.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: Onboarding guide
title: Onboarding
weight: 10
---
4 changes: 2 additions & 2 deletions docs/000-onboarding/ambassador-guide.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Onboarding Guide for AsyncAPI Ambassadors
weight: 110
weight: 50
---


Expand Down Expand Up @@ -38,4 +38,4 @@ Examples:
- Our sincere gratitude and respect for your contributions!

### Additional resources
[AsyncAPI Ambassador Program](https://github.com/asyncapi/community/blob/master/AMBASSADOR_ORGANIZATION.md)
[AsyncAPI Ambassador Program](../050-mentorship-program/ambassador-program/AMBASSADOR_PROGRAM.md)
14 changes: 7 additions & 7 deletions docs/000-onboarding/docs-onboarding-checklist.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
---
title: 'Docs onboarding checklist'
weight: 30
title: Docs Onboarding Checklist
weight: 60
---
## AsyncAPI docs onboarding checklist

As an open-source initiative with a global community, technical writer contributors should learn about our governance documents, documentation processes, and communication channels.

Complete in order the following onboarding tasks:

- [ ] Read the [AsyncAPI Code of Conduct](https://github.com/asyncapi/community/blob/master/CODE_OF_CONDUCT.md).
- [ ] Read the [AsyncAPI Slack etiquette](https://github.com/asyncapi/community/blob/master/slack-etiquette.md).
- [ ] Read the [AsyncAPI Code of Conduct](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md).
- [ ] Read the [AsyncAPI Slack etiquette](../060-meetings-and-communication/slack-etiquette.md).
- [ ] Join [the AsyncAPI Slack workspace](https://asyncapi.com/slack-invite).
- [ ] Add the AsyncAPI calendar found in [the AsyncAPI events page](https://www.asyncapi.com/community/events).
- [ ] Read the list of [technical writer contributor responsibilities](../010-contribution-guidelines/technical-writer-contributor-responsibilities).
- [ ] Read and familiarize yourself with the [prerequisite knowledge topics](../010-contribution-guidelines/prerequisite-knowledge).
- [ ] Read the list of [technical writer contributor responsibilities](../010-contribution-guidelines/technical-writer-contributor-responsibilities.md).
- [ ] Read and familiarize yourself with the [prerequisite knowledge topics](../010-contribution-guidelines/prerequisite-knowledge.md).
- [ ] Familiarize yourself with the _work-in-progress_ [AsyncAPI Style Guide](https://github.com/asyncapi/community/pulls?q=is%3Apr+is%3Aopen+style+guide).
- [ ] Read all docs under the following content buckets: `Concepts`, `Tutorials`, `Reference`. (Take the time to go through each tutorial.)
- [ ] Set up your local environment following our instructions for the [AsyncAPI git workflow](https://github.com/asyncapi/community/blob/master/git-workflow.md).
- [ ] Set up your local environment following our instructions for the [AsyncAPI git workflow](../010-contribution-guidelines/git-workflow.md).
- [ ] Introduce yourself in AsyncAPI Slack in the `#01_introductions` channel and the `#13_docs` channel. Ask docs-related questions in #13_docs.
- [ ] Request a good first docs issue in the [`#13_docs` Slack channel](https://asyncapi.com/slack-invite).
- [ ] Attend [OPEN docs meetings](https://www.asyncapi.com/community/events) to chat with other maintainers, ask docs questions, and request help on docs blockers.
5 changes: 5 additions & 0 deletions docs/000-onboarding/documentarian-onboarding-guide.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
---
title: Documentarian Onboarding Guide
weight: 30
---

🚧 This document is under construction.

Please be patient as we work on it. Thank you. 🫶
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: 'Utilizing GitHub Actions'
weight: 140
title: Utilizing GitHub Actions
weight: 80
---

## Overview
Expand Down
5 changes: 5 additions & 0 deletions docs/000-onboarding/how-to-contribute.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
---
title: How to Contribute
weight: 20
---

🚧 This document is under construction.

Please be patient as we work on it. Thank you. 🫶
6 changes: 3 additions & 3 deletions docs/000-onboarding/index.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
title: 'Introduction'
weight: 10
title: Introduction
weight: 5
---
## Technical writer onboarding guide

The AsyncAPI technical writer onboarding guide teaches new community members how to contribute to our documentation effectively.

> For a comprehensive understanding of the various ways you can contribute to the AsyncAPI Initiative, please consult the [AsyncAPI contributing guidelines](https://github.com/asyncapi/community/blob/master/CONTRIBUTING.md).
> For a comprehensive understanding of the various ways you can contribute to the AsyncAPI Initiative, please consult the [AsyncAPI contributing guidelines](../../CONTRIBUTING.md).

The goal is providing docs contributors with the necessary tools and knowledge to:

Expand Down
4 changes: 2 additions & 2 deletions docs/000-onboarding/maintainer-guide.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Onboarding Guide for AsyncAPI Maintainers
weight: 100
weight: 40
---


Expand Down Expand Up @@ -46,7 +46,7 @@ Before you can become a **maintainer**, you need to start as a **contributor**.

### 2. Open a PR

For a comprehensive guide on how to create a fork and start contributing, refer to the [AsyncAPI Git Workflow Guide](https://github.com/asyncapi/community/blob/master/git-workflow.md).
For a comprehensive guide on how to create a fork and start contributing, refer to the [AsyncAPI Git Workflow Guide](../010-contribution-guidelines/git-workflow.md).

- **Fork the repository**: Fork the repository you want to contribute to and create a new branch for your changes.

Expand Down
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
title: Upholding the Code of Conduct for new contributors
title: Upholding the Code of Conduct
description: This onboarding guide outlines how to uphold the Code of Conduct document for new contributors
weight: 160
weight: 70
---

# Contributor Guide to Upholding the Code of Conduct

Welcome to the AsyncAPI community! As a contributor, you are an essential part of building a safe, inclusive, and respectful environment for everyone. This guide will help you understand how to follow and uphold our [Code of Conduct](https://github.com/asyncapi/community/blob/master/CODE_OF_CONDUCT.md).
Welcome to the AsyncAPI community! As a contributor, you are an essential part of building a safe, inclusive, and respectful environment for everyone. This guide will help you understand how to follow and uphold our [Code of Conduct](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md).



Expand All @@ -29,7 +29,7 @@ Following it helps:
- **Be community-oriented:** Encourage collaboration, help others when you can, and gracefully accept constructive criticism.
- **Speak Up:** If you witness inappropriate behavior, report it.

You are expected to read and understand the full [CoC](https://github.com/asyncapi/community/blob/master/CODE_OF_CONDUCT.md) before contributing.
You are expected to read and understand the full [CoC](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md) before contributing.


## What to Do If You Experience or Witness a Violation
Expand All @@ -44,7 +44,7 @@ If you experience or observe discrimination, harassment, or any behavior that vi
### 2. Report the Incident
You can report a CoC violation by:

- Emailing **[email protected]** – this forwards directly to the [Code of Conduct Committee](https://github.com/asyncapi/community/blob/master/code_of_conduct/code-of-conduct-committee.md)
- Emailing **[email protected]** – this forwards directly to the [Code of Conduct Committee](../CODE_OF_CONDUCT_COMMITTEE.md)
- Reaching out to a specific CoC Committee member if the issue involves someone on the committee

All reports are handled with confidentiality, respect, and prompt action.
Expand All @@ -61,5 +61,5 @@ The Code of Conduct Committee is trained to resolve conflicts fairly and ensure


## Additional Resources
- [Incident Resolution Procedures](https://github.com/asyncapi/community/blob/master/code_of_conduct/coc-incident-resolution-procedures.md)
- [Slack Etiquette Guidelines](https://github.com/asyncapi/community/blob/master/slack-etiquette.md)
- [Incident Resolution Procedures](../COC-incident-resolution-procedures.md)
- [Slack Etiquette Guidelines](../060-meetings-and-communication/slack-etiquette.md)
5 changes: 5 additions & 0 deletions docs/000-onboarding/where-to-contribute.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
---
title: Where to Contribute
weight: 10
---

🚧 This document is under construction.

Please be patient as we work on it. Thank you. 🫶
7 changes: 6 additions & 1 deletion docs/010-contribution-guidelines/BOUNTY_PROGRAM.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
---
title: AsyncAPI Bounty Program
weight: 160
---

# AsyncAPI Bounty Program


Expand Down Expand Up @@ -30,7 +35,7 @@ The approximate maximum quantity of Bounty Issues per calendar quarter round var

Bounty Program Participants are prioritized in the following order:

1. AsyncAPI Maintainers (from the Bounty Issue's repository), checked at https://github.com/asyncapi/community/blob/master/MAINTAINERS.yaml
1. AsyncAPI Maintainers (from the Bounty Issue's repository), checked at [MAINTAINERS.yaml](../../MAINTAINERS.yaml)

2. Regular contributors (GitHub users who have three or more Pull Requests merged throughout the AsyncAPI GitHub Organization, checked with https://github.com/search?q=org%3Aasyncapi+is%3Apr+is%3Amerged+author%3Agh_username).

Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
---
title: Become Maintainer in Existing Project
weight: 140
---

### Become Maintainer in Existing Project

We know you are nervous about making your first contribution. In this section, we guide you on the steps towards becoming a TSC member:
Expand All @@ -18,7 +23,7 @@ Here's how to select an issue to contribute to:

**Step 2: Open a Pull Request**

To open a pull request successfully, follow our [Git workflows contributors guide](https://github.com/asyncapi/community/blob/master/git-workflow.md).
To open a pull request successfully, follow our [Git workflows contributors guide](git-workflow.md).

Use the following steps to open your pull request:
1. Configure a fork
Expand All @@ -40,4 +45,4 @@ After making several contributions to AsyncAPI, maintainers will recognize you.

Once you become a maintainer in one of the repositories, you can apply to join a group of [TSC members](https://www.asyncapi.com/community/tsc).

Open a PR in the **community** repository to add your name to the [list of TSC members](https://github.com/asyncapi/community/blob/master/TSC_MEMBERS.json). Specify your name, repositories that you maintain, and if you are sponsored by some company. For example [see this PR that introduced one of the new TSC members](https://github.com/asyncapi/community/pull/277).
Open a PR in the **community** repository to add your name to the [list of TSC members](../../TSC_BOARD_MEMBERS.yaml). Specify your name, repositories that you maintain, and if you are sponsored by some company. For example [see this PR that introduced one of the new TSC members](https://github.com/asyncapi/community/pull/277).
4 changes: 4 additions & 0 deletions docs/010-contribution-guidelines/_section.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: Contribution Guidelines
weight: 20
---
8 changes: 4 additions & 4 deletions docs/010-contribution-guidelines/code-contributor-guide.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: AsyncAPI Code Contributor Guide
description: A guide for new contributors looking to contribute code to the AsyncAPI project.
weight: 90
weight: 70
---
# AsyncAPI Code Contributor Guide

Expand All @@ -13,14 +13,14 @@ Welcome to the AsyncAPI community! We're excited to have you here. Think of Asyn
## 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 Workflow Guide](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.

## 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)
1. Follow the [Code of Conduct](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md)
2. Stick to the [Contributing guidelines](../../CONTRIBUTING.md)
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.

Expand Down
5 changes: 5 additions & 0 deletions docs/010-contribution-guidelines/contribute-blog-post.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
---
title: Contribute AsyncAPI Blog Posts
weight: 90
---

## Contribute AsyncAPI blog posts

The AsyncAPI blog is open to everyone; any contribution is allowed, including reposting. You can share use cases, projects, or tools in the form of a blog post to reach out to the entire AsyncAPI community.
Expand Down
2 changes: 1 addition & 1 deletion docs/010-contribution-guidelines/contribute-to-docs.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Contribute to docs
weight: 70
weight: 80
---

## Contribute to docs
Expand Down
14 changes: 7 additions & 7 deletions docs/010-contribution-guidelines/contribution-flow.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Simple contribution flow for contributors
weight: 130
title: Simple Contribution Flow
weight: 20
---

# Simple Contribution Flow
Expand All @@ -20,18 +20,18 @@ At AsyncAPI, we value **quality over quantity**. This guide will help you make m
### Before Making a Contribution
- Read the [onboarding contributor guide](https://www.asyncapi.com/docs/community/onboarding-guide).
- If you are contributing to the community repository, review the [documentation onboarding checklist](https://www.asyncapi.com/docs/community/onboarding-guide/docs-onboarding-checklist).
- For other repositories, refer to the [general contribution guidelines](https://github.com/asyncapi/community/blob/master/CONTRIBUTING.md).
- For other repositories, refer to the [general contribution guidelines](../../CONTRIBUTING.md).
- Look through existing issues and pull requests to understand the repository better.
- Check the [general roadmap](https://www.asyncapi.com/roadmap).

### Steps to making a good contribution
1. Set up your workflow environment using the [git workflow guide](/asyncapi/community/blob/master/git-workflow.md).
1. Set up your workflow environment using the [git workflow guide](git-workflow.md).
2. Search for [good first issues](https://github.com/issues?page=1&q=is%3Aopen+org%3Aasyncapi+sort%3Aupdated-desc+label%3A%22good+first+issue%22).
3. When you find one, comment on your interest and share the approach to solving the issue (please don't ask to be assigned, as it could be flagged as spam).
4. If you noticed a bug, typo, or needed improvement, feel free to create an issue.
5. **Make a PR only after a maintainer assigned the issue to you or asks you to work on it** even if you created the issue yourself.
6. Follow the [conventional commits guide](https://github.com/asyncapi/community/blob/master/docs/010-contribution-guidelines/conventional-commits.md) to write a good PR title.
7. Follow the [git workflow document](/asyncapi/community/blob/master/git-workflow.md) when working on your changes and making a PR.
6. Follow the [conventional commits guide](conventional-commits.md) to write a good PR title.
7. Follow the [git workflow document](git-workflow.md) when working on your changes and making a PR.
8. After making a PR, patiently wait for reviews.
9. Make sure all your PR checks pass (turn green) to speed up the merging process.
10. If your PR hasn’t been reviewed after **a week and a half**, you can gently remind a maintainer on Slack or GitHub. Delays can happen for various reasons, but no one is ignoring you! 🙏🏼 .
Expand All @@ -46,7 +46,7 @@ These rules are here to help you succeed and to support the maintainers and comm
- **Be patient**. Maintainers are volunteers with their jobs, families, and responsibilities. It may take time for your PR or issue to be reviewed.
- **Use the right Slack channels**. If you're unsure where to post, ask politely or take a moment to check.
- **Keep Slack tidy**. Use threads for conversations, avoid tagging `@maintainers` unless truly necessary, and don’t spam.
- Follow our [Slack etiquette](https://github.com/asyncapi/community/blob/master/slack-etiquette.md) and [Code of Conduct](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md).
- Follow our [Slack etiquette](../060-meetings-and-communication/slack-etiquette.md) and [Code of Conduct](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md).
- **Respect others**. Treat everyone with kindness and patience. We are all here to learn and grow together.

### ❌ What You Should Never Do
Expand Down
4 changes: 2 additions & 2 deletions docs/010-contribution-guidelines/conventional-commits.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Following Conventional Commits
description: This guide teaches you how to write clear and structured commit messages using the Conventional Commits standard.
weight: 120
weight: 60
---

When you contribute to a project, you're not just adding code or docs but also context. Your changes become part of the project's history, and your commit messages explain why the changes were made.
Expand Down Expand Up @@ -42,7 +42,7 @@ The following are some of the most commonly used commit types:

To maintain a clear and structured commit history, all PR titles must follow the Conventional Commits format. This ensures that commit messages and PRs are semantically meaningful and easy to understand.

A PR title that does not follow this format will be rejected by our [Linting bot](https://github.com/asyncapi/community/blob/master/.github/workflows/lint-pr-title.yml), preventing the PR from being merged.
A PR title that does not follow this format will be rejected by our [Linting bot](../../.github/workflows/lint-pr-title.yml), preventing the PR from being merged.

Therefore, you can use the following examples to guide you:

Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title : 'Create new docs directories'
weight : 80
title: Create New Docs Directories
weight: 120
---

### Create new docs directories
Expand Down
5 changes: 5 additions & 0 deletions docs/010-contribution-guidelines/git-workflow.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
---
title: Git Workflow
weight: 50
---

# Git Workflow

This document is the best practice guide that contains the rules to follow when working with AsyncAPI repositories.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Identifying Good First Issues
description: A guide to help new contributors find and work on beginner-friendly issues in AsyncAPI projects
weight: 50
weight: 40
---

# Identifying Good First Issues
Expand Down Expand Up @@ -73,7 +73,7 @@ AsyncAPI follows a "first come, first served" approach for assigning issues. Her
- **Comment on the issue:** Start with saying something like, "Hey, I'd like to work on this!" so maintainers know you're interested.

- **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, head on to the [git workflow guide](https://github.com/asyncapi/community/blob/master/git-workflow.md), and start working!
- **Start coding**: Once approved, head on to the [git workflow guide](git-workflow.md), 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!
32 changes: 32 additions & 0 deletions docs/010-contribution-guidelines/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
title: Getting Started with Contributions
weight: 5
---

This section covers everything you need to know about contributing to AsyncAPI:

**Getting Started**
- Essential prerequisite knowledge and skills needed
- Tools and development environment setup
- How to identify good first issues for new contributors

**Development Workflow**
- Git workflow and branching strategies
- Conventional commit standards
- Step-by-step contribution flow process

**Content Creation**
- Guidelines for contributing blog posts
- Documentation contribution standards
- Creating new documentation directories
- Opening effective pull requests

**Advanced Contributions**
- Code contribution guidelines and best practices
- Technical writer responsibilities and standards
- Recognition and credit systems for contributors

**Leadership and Mentoring**
- How to mentor other maintainers
- Path to becoming a maintainer in existing projects
- Information about the AsyncAPI Bounty Program
Loading