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

> Learn how to contribute to the datawhalechina/hello-agents project. Fork, branch, modify docs code or community files, and submit a pull request to share your improvements.

- Repository: [Datawhale/hello-agents](https://github.com/datawhalechina/hello-agents)
- Tags: how-to-guide
- Published: 2026-05-09

---

**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`](https://github.com/datawhalechina/hello-agents/blob/main/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`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter9/codebase_maintainer.py) implements a full-stack code-base maintainer agent, while [`code/chapter9/project/main.py`](https://github.com/datawhalechina/hello-agents/blob/main/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`](https://github.com/datawhalechina/hello-agents/blob/main/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`](https://github.com/datawhalechina/hello-agents/blob/main/.github/ISSUE_TEMPLATE/config.yml) and [`.github/ISSUE_TEMPLATE/book_issue.yml`](https://github.com/datawhalechina/hello-agents/blob/main/.github/ISSUE_TEMPLATE/book_issue.yml) to propose new ideas.

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

```bash
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:

```bash
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:

```bash

# 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`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter9/project/main.py), fix it as follows:

```bash

# 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:

```bash

# 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:

```bash

# 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`](https://github.com/datawhalechina/hello-agents/blob/main/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`](https://github.com/datawhalechina/hello-agents/blob/main/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`](https://github.com/datawhalechina/hello-agents/blob/main/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`](https://github.com/datawhalechina/hello-agents/blob/main/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`](https://github.com/datawhalechina/hello-agents/blob/main/.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`](https://github.com/datawhalechina/hello-agents/blob/main/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`](https://github.com/datawhalechina/hello-agents/blob/main/README.md)) to link to your contribution so other community members can discover it.