Skip to content

docs: add beginner-friendly contributor setup guide#3237

Open
felipeofdev-ai wants to merge 1 commit intoAutoMQ:mainfrom
felipeofdev-ai:codex/add-beginner-friendly-contributor-setup-guide
Open

docs: add beginner-friendly contributor setup guide#3237
felipeofdev-ai wants to merge 1 commit intoAutoMQ:mainfrom
felipeofdev-ai:codex/add-beginner-friendly-contributor-setup-guide

Conversation

@felipeofdev-ai
Copy link
Copy Markdown

Summary

This PR adds a comprehensive local setup guide for new contributors, addressing issue #3105.

The guide was written from the perspective of a first-time contributor who completed the full onboarding process and documented every friction point encountered along the way.

What's included

  • Prerequisites checklist with exact verification commands
  • Fork & clone steps including upstream remote configuration
  • Step-by-step Docker-based local environment setup with exact commands (tag 1.5.5)
  • Producer test to verify the broker is running correctly
  • Build and test instructions using the Gradle wrapper (./gradlew)
  • Key modules overview table (s3stream, core, automq-metrics, automq-shell, docker, examples)
  • Full contribution workflow from issue claim (/assign) to signed CLA and merged PR
  • Community channels table (GitHub Issues, Slack, WeChat, Gurubase, DeepWiki)
  • Commands cheat sheet at the end for quick reference

Motivation

Issue #3105 identified that new contributors lack a single, clear entry point for getting productive locally. This guide eliminates that friction by consolidating all setup steps, commands, and context in one place.

Closes #3105

@CLAassistant
Copy link
Copy Markdown

CLAassistant commented Feb 24, 2026

CLA assistant check
All committers have signed the CLA.

Copy link
Copy Markdown

@lobsangshakya lobsangshakya left a comment

Choose a reason for hiding this comment

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

Great Work!

Small suggestion: the port verification command (lsof -i) is Unix-specific.
It might help first-time contributors if we add equivalent commands for macOS and Windows, or mention that this step is platform-dependent.

@lobsangshakya
Copy link
Copy Markdown

Question: does the Docker Compose setup always create the automq_net network with this exact name? If not, we could mention how to confirm the network via docker network ls to avoid confusion.

@Gezi-lzq
Copy link
Copy Markdown
Contributor

Compared to the existing CONTRIBUTING_GUIDE.md, could you explain why a separate file is necessary? The existing guide already covers Docker setup, build instructions, contribution workflow, and community channels. What specific gaps does this new guide address that couldn't be resolved by improving the existing documentation?
Having two similar guides may confuse new contributors and increase maintenance overhead.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: beginner-friendly local setup guide for new contributors

4 participants