How to Contribute to the datawhalechina/hello-agents Project: A Complete Guide

Contributing to the datawhalechina/hello-agents project involves forking the repository, creating a feature branch to modify files in docs/, code/, or community folders, and submitting a pull request after validating changes against the existing Python examples.

The datawhalechina/hello-agents repository is a community-driven tutorial that teaches developers how to build AI-native agents from the ground up. The project welcomes contributions ranging from bug fixes and documentation improvements to entirely new tutorial chapters and real-world project templates. According to the source code in README.md (lines 35-44), contributors can report bugs, propose ideas, submit pull requests, or share practical implementations.

Understanding the Repository Structure

Before contributing, familiarize yourself with how content is organized. The repository uses a clear separation between tutorial text, executable code, and community extras.

Core Directories

• docs/ – Contains the main tutorial markdown files (chapter1/, chapter2/, etc.) that render on the official website. These files synchronize with the accompanying code examples.

• code/ – Houses runnable Python scripts that demonstrate concepts from each chapter. For example, code/chapter9/codebase_maintainer.py implements a full-stack code-base maintainer agent, while code/chapter9/project/main.py provides entry points for chapter-specific demos.

• Extra-Chapter/ – Stores supplemental material including interview Q&A, skill-writing guides, and community blog posts contributed by learners.

• Co-creation-projects/ – Holds real-world project templates like the Travel Assistant or Pixel Personal-Information Signaling System submitted by community members.

The Contribution Workflow

The project follows a standard fork-branch-PR workflow to keep the main repository clean and reviewable.

1. Prepare Your Environment

Start by reading the contribution guidelines in README.md, which outline the open-source spirit and specific actions you can take. Browse the Issues tab to find existing tasks or use the structured templates in .github/ISSUE_TEMPLATE/config.yml and .github/ISSUE_TEMPLATE/book_issue.yml to propose new ideas.

Fork the repository on GitHub, then clone your fork locally:

git clone https://github.com/<your-username>/hello-agents.git
cd hello-agents
git remote add upstream https://github.com/datawhalechina/hello-agents.git

2. Create a Feature Branch

Always work on a separate branch to isolate your changes:

git checkout -b my-contribution

3. Make Targeted Changes

Depending on your contribution type, modify the appropriate files:

• Documentation fixes – Edit markdown files under docs/
• Code improvements – Update Python scripts under code/
• Community content – Add files to Extra-Chapter/ or Co-creation-projects/

Practical Contribution Examples

Adding a New Tutorial Chapter

To add Chapter 17 to the tutorial series:

# Create the new chapter directory and file

mkdir docs/chapter17
cp docs/chapter16/第十六章\ 毕业设计.md docs/chapter17/第十七章\ 新章节.md

# Edit the content with your preferred editor

# Update the navigation sidebar

vim docs/_sidebar.md

# Stage and commit

git add docs/chapter17/ docs/_sidebar.md
git commit -m "Add Chapter 17 – Advanced Agent Deployment"
git push origin my-contribution

Fixing a Code Example

If you discover a syntax error in code/chapter9/project/main.py, fix it as follows:

# Sync with upstream first

git checkout main
git pull upstream main
git checkout -b fix-main-py

# Fix the error (example: correcting a print statement)

sed -i 's/print("Hello"/print("Hello")/' code/chapter9/project/main.py

# Validate the fix

python code/chapter9/project/main.py

# Commit the correction

git add code/chapter9/project/main.py
git commit -m "Fix syntax error in main.py"
git push origin fix-main-py

Contributing a Community Blog Post

To share your learning experience via the Extra-Chapter section:

# Create your contribution

touch Extra-Chapter/Extra11-My-Experience.md
echo "# My Experience with Hello-Agents" >> Extra-Chapter/Extra11-My-Experience.md

# ... add your content ...

# Update the index in README.md if applicable

git add Extra-Chapter/Extra11-My-Experience.md README.md
git commit -m "Add Extra-Chapter blog post about learning journey"
git push origin my-extra11

Validating Your Changes

Before submitting, verify that your modifications do not break existing functionality. Most examples are pure-Python and can be executed locally:

# Test a specific chapter's code

python code/chapter9/project/main.py

# Or run the specific script you modified

python code/chapter9/codebase_maintainer.py

The repository's CI system automatically triggers on pull requests to catch regressions, but local testing speeds up the review process.

Submitting Your Contribution

Once your changes are tested and committed:

1. Push your branch to your fork: git push origin my-contribution
2. Open a Pull Request on GitHub using the provided template
3. Reference related issues in the description (e.g., "Closes #123")
4. Wait for maintainer review and address any feedback

When your PR is merged, your contribution appears in the project's Community Contribution section and the repository's contribution graph.

Summary

• Repository structure: Tutorial content lives in docs/, executable examples in code/, and community extras in Extra-Chapter/ and Co-creation-projects/
• Entry points: Check README.md (lines 35-44) for contribution guidelines and use the YAML templates in .github/ISSUE_TEMPLATE/ for structured issue creation
• Workflow: Fork → Branch → Edit → Validate → Commit → Push → PR
• Validation: Run Python examples locally (e.g., code/chapter9/project/main.py) before submitting to ensure compatibility
• Recognition: Merged contributions are acknowledged in the community section and contribution graph

Frequently Asked Questions

What types of contributions does the datawhalechina/hello-agents project accept?

The project accepts bug reports, documentation improvements, new tutorial chapters, code examples, and community-driven projects. According to the README.md contribution section (lines 35-44), you can report bugs, propose ideas, submit PRs, or share practical implementations in the Extra-Chapter/ and Co-creation-projects/ directories.

Do I need to run tests before submitting a pull request?

Yes. You should verify that your changes do not break the tutorial scripts by running the relevant Python files locally. For example, if you modified code/chapter9/project/main.py, execute python code/chapter9/project/main.py to confirm it runs without errors. The repository's CI will also run checks automatically when you open the PR.

How do I propose a new tutorial chapter or book-style contribution?

Use the structured issue template provided in .github/ISSUE_TEMPLATE/book_issue.yml when creating a new issue. This template ensures you provide the necessary context for maintainers to evaluate your proposal. After discussion, you can follow the workflow for adding new markdown files under docs/ and update the navigation sidebar in docs/_sidebar.md.

Where should I place community project templates or interview guides?

Place real-world project templates in the Co-creation-projects/ directory. For interview Q&A, skill-writing guides, or blog-style posts, use the Extra-Chapter/ directory. After adding your content, update the relevant index files (such as README.md) to link to your contribution so other community members can discover it.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}