Contributing to MassGen

Contents

Contributing to MassGen#

Full Contributing Guide#

Contributing to MassGen#

Thank you for your interest in contributing to MassGen (Multi-Agent Scaling System for GenAI)! We welcome contributions from the community and are excited to see what you’ll bring to the project.

📍 Looking for what to work on? Check ROADMAP.md for:

  • Active development tracks with owners

  • Upcoming release features and priorities

  • Long-term vision and goals

This guide covers: Development setup, code standards, testing, PR process, and documentation requirements.

🛠️ Development Guidelines#

Project Structure#
massgen/
├── __init__.py              # Main package exports
├── cli.py                   # Command-line interface
├── orchestrator.py          # Multi-agent coordination
├── chat_agent.py            # Chat agent implementation
├── agent_config.py          # Agent configuration management
├── message_templates.py     # Message template system
├── logger_config.py         # Logging configuration
├── utils.py                 # Helper functions and model registry
├── task_decomposer.py       # Task decomposition for decomposition coordination mode
├── infrastructure/          # Infrastructure utilities
│   ├── worktree_manager.py  # Git worktree create/remove/list/prune
│   └── shadow_repo.py       # Shadow repo for non-git directories
├── filesystem_manager/      # Filesystem management
│   ├── _isolation_context_manager.py # Worktree isolation for agent writes
│   └── _change_applier.py   # Apply approved changes from worktree
├── backend/                 # Model-specific implementations
│   ├── __init__.py
│   ├── base.py             # Base backend interface
│   ├── cli_base.py         # CLI backend base class
│   ├── chat_completions.py # Chat completion utilities
│   ├── response.py         # Response handling
│   ├── azure_openai.py     # Azure OpenAI backend
│   ├── claude.py           # Anthropic Claude backend
│   ├── claude_code.py      # Claude Code CLI backend
│   ├── codex.py            # OpenAI Codex CLI backend
│   ├── native_tool_mixin.py # Native tool backend mixin
│   ├── gemini.py           # Google Gemini backend
│   ├── grok.py             # xAI Grok backend
│   ├── lmstudio.py         # LMStudio backend
│   └── *.md                # Backend documentation and API research
├── mcp_tools/              # MCP (Model Context Protocol) integration
│   ├── __init__.py
│   ├── README.md           # Comprehensive MCP documentation
│   ├── backend_utils.py    # Backend utility functions for MCP
│   ├── circuit_breaker.py  # Circuit breaker pattern implementation
│   ├── client.py           # MCP client implementation
│   ├── config_validator.py # Configuration validation
│   ├── converters.py       # Data format converters
│   ├── exceptions.py       # Custom MCP exceptions
│   ├── security.py         # Security validation and sanitization
│   ├── filesystem_manager.py # Workspace and snapshot management
│   ├── hooks.py            # Function hooks for permission management
│   ├── custom_tools_server.py # Custom tools MCP server for CLI backends
│   ├── workflow_tools_server.py # Workflow tools MCP server
│   ├── workspace_copy_server.py # MCP server for file copying operations
│   └── *.md                # Individual component documentation
├── frontend/               # User interface components
│   ├── __init__.py
│   ├── coordination_ui.py  # Main UI coordination
│   ├── displays/           # Display implementations
│   │   ├── __init__.py
│   │   ├── base_display.py
│   │   ├── rich_terminal_display.py
│   │   ├── simple_display.py
│   │   └── terminal_display.py
├── configs/                # Configuration files
│   ├── *.yaml             # Various agent configurations
│   └── *.md               # MCP setup guides and documentation
├── tests/                  # Test files
│   ├── __init__.py
│   ├── test_*.py          # Test implementations
│   └── *.md               # Test documentation and case studies
└── v1/                     # Legacy version 1 code
    ├── __init__.py
    ├── agent.py
    ├── agents.py
    ├── backends/
    ├── cli.py
    ├── config.py
    ├── examples/
    ├── logging.py
    ├── main.py
    ├── orchestrator.py
    ├── streaming_display.py
    ├── tools.py
    ├── types.py
    └── utils.py
Adding New Model Backends#

To add support for a new model provider:

  1. Create a new file in massgen/backend/ (e.g., new_provider.py)

  2. Inherit from the base backend class in massgen/backend/base.py

  3. Implement the required methods for message processing and completion parsing

  4. Add the model mapping in massgen/utils.py

  5. Add backend capabilities to massgen/backend/capabilities.py - Required for config validation

  6. Update configuration templates in massgen/configs/

  7. Add tests in massgen/tests/

  8. Update the config validator - See Updating the Config Validator below

  9. Update documentation

Updating the Config Validator#

⚠️ IMPORTANT: Whenever you add new configuration options, backends, or change the config schema, you MUST update the config validator.

The config validator (massgen/config_validator.py) ensures users get helpful error messages when they make configuration mistakes. When you add a new feature:

1. Add to Backend Capabilities (for new backends)

# In massgen/backend/capabilities.py
BACKEND_CAPABILITIES = {
    # ...
    "your_backend": BackendCapabilities(
        backend_type="your_backend",
        provider_name="Your Backend Name",
        supported_capabilities={"mcp", "web_search", ...},
        builtin_tools=[...],
        filesystem_support="mcp",
        models=["model-1", "model-2"],
        default_model="model-1",
        env_var="YOUR_API_KEY",
        notes="Description of your backend",
    ),
}

2. Update Validator Enums (for new config options)

# In massgen/config_validator.py
# If adding new valid values for existing fields:
VALID_PERMISSION_MODES = {"default", "acceptEdits", "bypassPermissions", "plan"}
VALID_DISPLAY_TYPES = {"rich_terminal", "simple"}

3. Add Validation Logic (for new config fields)

# In massgen/config_validator.py
# Add validation in the appropriate _validate_* method
def _validate_your_feature(self, config, result):
    if "your_field" in config:
        # Validate type
        # Validate values
        # Add helpful error messages

4. Add Tests for Common Mistakes

# In massgen/tests/test_config_validator.py
def test_invalid_your_feature(self):
    """Test invalid your_feature value."""
    config = {
        "your_field": "invalid_value",
        # ...
    }
    validator = ConfigValidator()
    result = validator.validate_config(config)
    assert not result.is_valid()
    assert any("your helpful error message" in error.message for error in result.errors)

5. Test Validation

# Validate all example configs still pass
uv run python scripts/validate_all_configs.py

# Run validator tests
uv run pytest massgen/tests/test_config_validator.py -v

Why This Matters:

  • Users get clear, actionable error messages instead of cryptic failures

  • Prevents common configuration mistakes

  • Makes the framework more accessible to new users

  • Pre-commit hooks automatically validate configs in massgen/configs/

🔒 API Stability & Versioning#

MassGen is currently in Beta (v0.1.x). We’re rapidly iterating on features and patterns. Here’s what you can depend on:

Stability Levels#

🟢 Stable - We Maintain Backward Compatibility

  • CLI Command: massgen executable and basic invocation patterns

    • massgen --config <path> will continue to work

    • Standard flags like --help, --version

    • Exit codes and basic output format

  • Core YAML Configuration Schema: Basic structure for defining agents and running them

    • Top-level keys: agents, orchestrator, providers

    • Agent definition fields: name, backend, system_prompt

    • Model provider configuration structure

    • Guarantee: New fields may be added with sensible defaults. Breaking changes to existing fields require major version bump and migration guides.

🟡 Experimental - Evolving Rapidly, May Change

  • Orchestration & Coordination: Agent coordination mechanisms and voting systems

    • Binary decision framework with voting tools

    • Planning mode vs execution mode

    • Coordination configuration and agent selection logic

    • New coordination patterns being explored

  • Backend Implementations: Individual model provider adapters

    • Provider-specific settings and capabilities

    • Tool/MCP integration per backend

    • Multimodal support varies by provider

  • Advanced YAML Features:

    • Memory module configuration

    • Tool system configuration

    • MCP server setup and permissions

    • Multi-turn conversation settings

  • Python Library API: Internal APIs not yet released for public use

    • Use CLI + YAML for production workflows

    • Python API stability coming in future releases

  • Multimodal Support: Image, audio, video processing

    • Backend capabilities evolving

    • Configuration schema may change

🔴 Deprecated - Will Be Removed

  • v1/ directory: Legacy code from version 1

    • Scheduled for removal in v1.0.0

    • Don’t add features or dependencies on this code

What This Means for Contributors#

When contributing to stable areas:

  • Breaking changes require team discussion

  • Must provide deprecation warnings 2+ releases (1 week) in advance

  • Update migration documentation in CHANGELOG.md

When contributing to experimental areas:

  • Coordinate with track owners in ROADMAP.md before major changes

  • Document that features are experimental in user-facing docs

  • Breaking changes allowed but should be documented

When working with deprecated code:

  • No new features should be added

  • Migrations and cleanup PRs welcome

  • Help users migrate to new patterns

Version Policy#

Current (v0.1.x):

  • Minor breaking changes allowed for experimental features

  • Migration guides provided in CHANGELOG.md for any breaking changes

  • CLI and core YAML schema remain backward compatible

Future (v0.2.x+):

  • More features graduate to stable

  • Deprecation warnings before all removals

  • Broader stability guarantees

v1.0.0 and beyond:

  • Full stability commitment for public APIs

  • Semantic versioning strictly enforced

  • Clear upgrade paths for all breaking changes

Examples#

Stable - These will keep working:

# Basic agent configuration
agents:
  - name: researcher
    backend: openai
    model: gpt-5
    system_prompt: "You are a research assistant"

Experimental - May change:

# Orchestrator settings (features evolving)
orchestrator:
  snapshot_storage: "snapshots"
  agent_temporary_workspace: "temp_workspaces"

# Memory configuration (implemented in v0.1.5 - see docs/source/user_guide/memory.rst)
memory:
  enabled: true
  persistent_memory:
    enabled: true
    vector_store: "qdrant"

📋 Prerequisites#

  • Python 3.11 or higher

  • Git

  • API keys for the model providers you want to use

  • uv for dependency management (recommended)

🚀 Development Setup#

1. Fork and Clone#
# Fork the repository on GitHub first, then:
git clone https://github.com/YOUR_USERNAME/MassGen.git
cd MassGen

# Add upstream remote
git remote add upstream https://github.com/Leezekun/MassGen.git
2. Create Development Environment#
# Install uv for dependency management (if not already installed)
pip install uv

# Create virtual environment
uv venv

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

# Install project in editable mode with all dependencies
uv pip install -e .

# Install development dependencies
uv pip install -e ".[dev]"
3. Set Up Pre-commit Hooks#

Pre-commit hooks ensure code quality and consistency. Install them with:

# Install pre-commit hooks
pre-commit install

# Install pre-push hooks (runs non-API test lane before push)
pre-commit install --hook-type pre-push
4. Environment Configuration#

Create a .env file in the massgen directory as described in README

🔧 Development Workflow#

Important: Our next version is v0.1.88. If you want to contribute, please contribute to the dev/v0.1.88 branch (or main if dev/v0.1.88 doesn’t exist yet).

1. Create Feature Branch#
# Fetch latest changes from upstream
git fetch upstream

# Create feature branch from dev/v0.1.60 (or main if dev branch doesn't exist yet)
git checkout -b feature/your-feature-name upstream/dev/v0.1.88
2. Make Your Changes#

Follow these guidelines while developing:

  • Code Style: Follow existing patterns and conventions in the codebase

  • Documentation: Update docstrings and README if needed

  • Tests: Add tests for new functionality

  • Type Hints: Use type hints for better code clarity

3. Code Quality Checks#

Before committing, ensure your code passes all quality checks:

# Run pre-commit hooks on staged files
pre-commit run

# Or to check specific files:
pre-commit run --files path/to/file1.py path/to/file2.py

# Run individual tools on changed files:

# Get list of changed Python files
git diff --name-only --cached --diff-filter=ACM | grep '\.py$'

# Format changed files with Black
git diff --name-only --cached --diff-filter=ACM | grep '\.py$' | xargs black --line-length=79

# Sort imports in changed files
git diff --name-only --cached --diff-filter=ACM | grep '\.py$' | xargs isort

# Check changed files with flake8
git diff --name-only --cached --diff-filter=ACM | grep '\.py$' | xargs flake8 --extend-ignore=E203

# Type checking on changed files
git diff --name-only --cached --diff-filter=ACM | grep '\.py$' | xargs mypy

# Security checks on changed files
git diff --name-only --cached --diff-filter=ACM | grep '\.py$' | xargs bandit

# Lint changed files with pylint
git diff --name-only --cached --diff-filter=ACM | grep '\.py$' | xargs pylint

# For testing all files (only when needed):
pre-commit run --all-files
4. Testing#
# Default fast lane (recommended)
make test-fast

# Equivalent direct command
uv run pytest massgen/tests --run-integration -m "not live_api and not docker and not expensive" -q --tb=no

# Non-API push gate (used by pre-push hook)
uv run pytest massgen/tests --run-integration -m "not live_api and not docker and not expensive" -q --tb=no

# Run specific test file
uv run pytest massgen/tests/test_specific.py

# Run with coverage
uv run pytest --cov=massgen massgen/tests/

# Run integration-scope tests (non-API + API, depending on markers)
uv run pytest --run-integration

# Run live API tests (requires API keys, may incur cost)
uv run pytest --run-integration --run-live-api -m "integration and live_api"

# Run all tests (integration, expensive, and docker)
make test-all

# Test with different configurations
massgen --config @examples/basic/single/single_agent "Test question"

Test Markers - Use these when writing new tests:

Marker

When to Use

Example

@pytest.mark.integration

Multi-component integration behavior (scope marker)

Orchestrator + agent + tracker coordination

@pytest.mark.live_api

Test calls real external provider APIs

Testing actual model responses

@pytest.mark.expensive

Test is slow (>10s) or costs money

Large-scale coordination tests

@pytest.mark.docker

Test requires Docker to be running

Container execution tests

For external dependencies (binaries, services), use skipif:

requires_vhs = pytest.mark.skipif(
    not check_vhs_installed(),
    reason="VHS not installed (brew install vhs)"
)

@requires_vhs
def test_recording():
    ...

Best practices:

  • Unit tests should NOT require API keys or external services

  • Mock external dependencies when possible

  • Use markers to separate scope (integration) from cost/runtime gates (live_api, expensive, docker)

  • integration, live_api, expensive, and docker tests are skipped by default unless explicitly enabled

5. Commit Your Changes#
# Stage your changes
git add .

# Commit with descriptive message
# Pre-commit hooks will run automatically
git commit -m "feat: add support for new model provider"

# If pre-commit hooks fail, fix the issues and commit again

Commit message format:

  • feat: New feature

  • fix: Bug fix

  • docs: Documentation changes

  • test: Adding or updating tests

  • refactor: Code refactoring

  • style: Code style changes

  • perf: Performance improvements

  • ci: CI/CD changes

6. Push and Create Pull Request#
# Push to your fork
git push origin feature/your-feature-name

Then create a pull request on GitHub:

  • Base branch: dev/v0.1.88 (or main if dev branch doesn’t exist yet)

  • Compare branch: feature/your-feature-name

  • Add clear description of changes

  • Link any related issues

🔍 Pre-commit Hooks Explained#

Our pre-commit configuration includes:

Python Code Quality#

  • check-ast: Verify Python AST is valid

  • black: Code formatter (line length: 79)

  • isort: Import sorting

  • flake8: Style guide enforcement

  • pylint: Advanced linting (with custom disabled rules)

  • mypy: Static type checking

File Checks#

  • check-yaml: Validate YAML syntax

  • check-json: Validate JSON syntax

  • check-toml: Validate TOML syntax

  • check-docstring-first: Ensure docstrings come before code

  • trailing-whitespace: Remove trailing whitespace

  • fix-encoding-pragma: Add # -*- coding: utf-8 -*- when needed

  • add-trailing-comma: Add trailing commas for better diffs

Security#

  • detect-private-key: Prevent committing private keys

Package Quality#

  • pyroma: Check package metadata quality

Test Gate#

  • run-non-api-tests-on-push (pre-push): Runs the non-API lane before push:

    • uv run pytest massgen/tests --run-integration -m "not live_api and not docker and not expensive" -q --tb=no

🎯 How to Find Where to Contribute#

MassGen development is organized into tracks - focused areas with dedicated owners who can guide your contributions.

Step 1: Explore Active Tracks#

Visit ROADMAP.md to see all active tracks with their owners and contact info:

  • Tool System Refactoring - Unified tool system (@qidanrui)

  • Multimodal Support - Image, audio, video processing (@qidanrui)

  • AG2 Group Chat Patterns - Complex research workflows (@Eric-Shang)

  • Agent Adapter System - Unified agent interface (@Eric-Shang)

  • Irreversible Actions Safety - Safety controls (@franklinnwren)

  • Memory Module - Long-term memory implementation (@kitrakrev, @qidanrui, @ncrispino)

  • Final Agent Submit/Restart - Multi-step verification (@ncrispino)

  • Coding Agent Enhancements - File operations (@ncrispino)

  • DSPy Integration - Automated prompt optimization (@praneeth999)

  • Web UI - Visual interface (@voidcenter)

Step 2: Reach Out to Track Owner#

Before starting work:

  1. Open a GitHub issue describing your contribution idea

    • Include context, motivation, and approach

    • Link to related issues/PRs if applicable

  2. Start a Discord thread in #massgen channel

    • @ mention the track owner (Discord handle from ROADMAP.md)

    • Link to your GitHub issue

    • Discuss your idea with the track owner who can:

      • Point you to existing work

      • Suggest good first issues

      • Explain current priorities

      • Review designs before implementation

Example:

  • Open issue: “Add support for OpenAI o1-pro model”

  • Discord: “@danrui2020 I’d like to contribute to multimodal support. Opened issue #123 with details.”

Step 3: Create Your Own Track (Optional)#

Have a significant feature idea not covered by existing tracks?

  1. Open a GitHub issue describing the proposed track

  2. Start a thread in #massgen Discord channel linking to the issue

  3. Work with the MassGen dev team to define the track

  4. Become a track owner yourself!

Quick Contribution Ideas (No Track Coordination Needed)#

  • 🐛 Bug Fixes - Open an issue/PR for any bugs you find

  • 📝 Documentation - Improvements always welcome

  • 🧪 Tests - Increase coverage in any module

  • 🎨 Examples - New configuration templates or use cases

  • 💡 Feature Requests - Open an issue to discuss ideas

First-Time Contributors#

Good first issues: Check GitHub issues tagged good first issue

Quick wins:

  • Add backend support for a new model provider (see Adding New Model Backends)

  • Create example configurations for your use case

  • Write case studies using MassGen

📝 Pull Request Guidelines#

Before Submitting#

  • Code passes all pre-commit hooks

  • Tests pass locally

  • Documentation is updated if needed

  • Commit messages follow convention

  • PR targets dev/v0.1.88 branch (or main if dev branch doesn’t exist yet)

PR Description Should Include#

  • What: Brief description of changes

  • Why: Motivation and context

  • How: Technical approach taken

  • Testing: How you tested the changes

  • Screenshots: If UI changes (if applicable)

Review Process#

  1. Automated checks will run on your PR

  2. CodeRabbit will provide AI-powered code review comments

  3. Maintainers will review your code

  4. Address any feedback or requested changes

  5. Once approved, PR will be merged

CodeRabbit AI Reviews#

We use CodeRabbit for automated code reviews. Configuration is in .coderabbit.yaml.

Useful commands (in PR comments):

  • @coderabbitai review - Trigger incremental review

  • @coderabbitai resolve - Mark all comments as resolved

  • @coderabbitai summary - Regenerate PR summary

Applying suggestions:

  • Click “Commit suggestion” button on GitHub for simple fixes

  • For complex changes, address manually or use Claude Code

🐛 Reporting Issues#

When reporting issues, please include:

  • Python version

  • Operating system

  • Steps to reproduce

  • Expected vs actual behavior

  • Error messages/logs

  • Minimal reproducible example

🤝 Community#

  • Discord: Join the #massgen channel of AG2 Discord server: https://discord.gg/VVrT2rQaz5

  • X: Follow the official MassGen X account: https://x.com/massgen_ai

  • GitHub Issues: Report bugs and request features

  • GitHub Discussions: Ask questions and share ideas

🤖 Using Claude Code#

MassGen development is made easier with Claude Code. The CLAUDE.md file provides project-specific guidance for Claude Code sessions.

Key Files for Claude Code Users#

File

Purpose

CLAUDE.md

Project instructions for Claude Code (architecture, commands, workflows)

.coderabbit.yaml

CodeRabbit configuration for automated PR reviews

docs/dev_notes/release_checklist.md

Full release process documentation
Useful Skills#

MassGen includes Claude Code skills in massgen/skills/ – ensure to symlink to .claude/skills so Claude Code starts with them in its context (ask Claude how to do this; it’s in the CLAUDE.md):

  • release-prep v0.1.X - Prepare release documentation and announcements

  • model-registry-maintainer - Add new models to capabilities registry

  • massgen-config-creator - Create properly structured YAML configs

CodeRabbit CLI Integration#

After implementing changes, run CodeRabbit locally:

coderabbit --prompt-only

This provides AI review output that Claude Code can use to create fix task lists.

🚀 Release Process#

Automated Workflows#

Workflow

Trigger

What It Does

pypi-publish.yml

GitHub Release published

Builds and publishes to PyPI, triggers ReadTheDocs build

release-docs-automation.yml

Tag push v*.*.*

Validates announcement files exist

auto-release.yml

Tag push

Creates GitHub Release

docker-publish.yml

Release published

Publishes Docker images
For Maintainers: Release Checklist#

  1. Merge release PR to main (from dev/v0.1.X branch)

  2. Run /release-prep v0.1.X - Generates CHANGELOG entry, announcement draft

  3. Review and commit the generated files

  4. Create and push tag: git tag v0.1.X && git push origin v0.1.X

  5. Publish GitHub Release - Triggers PyPI auto-publish

  6. Post announcement - Copy from docs/announcements/current-release.md to LinkedIn/X

  7. Update links - Add social post URLs back to current-release.md

Announcement Files#

File

Purpose

docs/announcements/feature-highlights.md

Long-lived feature list (~3k chars for LinkedIn)

docs/announcements/current-release.md

Active release announcement

docs/announcements/archive/

Past announcements for reference

See docs/announcements/README.md for the full workflow.

⚠️ Important Notes#

Dependencies#

  • When adding new dependencies, update pyproject.toml

  • Use optional dependency groups for non-core features

  • Pin versions for critical dependencies

Backward Compatibility#

  • Maintain backward compatibility when possible

  • Document breaking changes clearly

  • Update version numbers appropriately

Performance Considerations#

  • Profile code for performance bottlenecks

  • Consider memory usage for large-scale operations

  • Optimize streaming and async operations

📚 Documentation Guidelines#

When Implementing a New Feature#

Every feature needs documentation! Here’s how to decide where and what to write.

1. Decide Where to Document#

Add to existing user guide when:

  • ✅ Feature extends existing functionality (e.g., new backend → add to backends.rst)

  • ✅ Natural fit in current documentation structure

  • ✅ Small enhancement (< 200 words of documentation)

Create new user guide when:

  • ✅ Feature is a major new capability (e.g., multi-turn mode)

  • ✅ Deserves its own page (> 500 words of documentation)

  • ✅ Introduces new concepts or workflows

Examples:

  • Adding new backend → Update user_guide/backends.rst

  • New MCP server → Add to user_guide/mcp_integration.rst

  • Update multi-turn conversation system → Edit user_guide/multi_turn_mode.rst

2. Required Documentation for Every Feature#

Always update these files:

  1. ✅ User Guide - How users interact with the feature

    • Location: docs/source/user_guide/

    • What to include: Usage examples, configuration, common patterns

  2. ✅ Configuration Docs - If feature adds config options

    • Location: docs/source/quickstart/configuration.rst

    • What to include: YAML examples, parameter descriptions

  3. ✅ Config Validator - REQUIRED if feature changes config schema

    • Location: massgen/config_validator.py and massgen/backend/capabilities.py

    • What to include: Validation logic, error messages, tests

    • See: Updating the Config Validator section above

  4. ✅ API Reference - If feature changes Python API

    • Location: docs/source/api/

    • What to include: Docstrings, function signatures, examples

  5. ✅ CHANGELOG.md - What changed in this version

    • Location: Root directory

    • What to include: Brief description under “Added”, “Changed”, or “Fixed”

  6. ✅ Examples - REQUIRED for every feature

    • Location: docs/source/examples/basic_examples.rst or feature-specific example files

    • What to include: Runnable code showing feature in action

    • Note: Examples are ALWAYS required, even if you write a case study. Case studies showcase real-world usage; examples show basic functionality.

3. Optional Design Documentation#

When to write additional documentation:

Design Doc (for complex implementation)#

Write when:

  • Implementation is complex and needs explanation for maintainers

  • Future contributors need to understand the design choices

  • Multiple approaches were considered

Location: docs/dev_notes/feature_name_design.md

Examples:

  • multi_turn_filesystem_design.md - Complex state management

  • gemini_filesystem_mcp_design.md - Integration architecture

Case Study (after feature is complete)#

Write when:

  • Want to demonstrate real-world usage

  • Feature is significant enough to showcase

  • Following case-driven development methodology

Location: docs/source/examples/case_studies/feature_name.md

Examples:

  • claude-code-workspace-management.md

  • unified-filesystem-mcp-integration.md

4. Documentation Decision Flowchart#
┌─────────────────────────────────────────┐
│  Implementing a New Feature             │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│  ALWAYS: Update user guide, config      │
│  docs, API docs, CHANGELOG.md           │
└────────────────┬────────────────────────┘
                 │
                 ▼
      Is implementation complex?
                 │
        Yes ──┬──┴──┬── No
              │     │
              ▼     └──────────────┐
   ┌──────────────────┐            │
   │ Write Design Doc │            │
   │ (dev_notes/)     │            │
   └──────┬───────────┘            │
          │                        │
          └────────────┬───────────┘
                       │
                       ▼
              Want to showcase
              real-world usage?
                       │
                  Yes──┼──No
                       │
                       ▼
                ┌──────────────┐
                │ Write Case   │
                │ Study        │
                │ (source/examples/case_studies/)│
                └──────────────┘
5. Quick Reference#

Document Type

When to Use

Location

Required?

User Guide

Every feature

docs/source/user_guide/

✅ Yes

Config Docs

Config changes

docs/source/quickstart/configuration.rst

✅ Yes

Config Validator

Config schema changes

massgen/config_validator.py

✅ Yes (if config changes)

API Docs

API changes

docs/source/api/

✅ Yes

CHANGELOG

Every PR

CHANGELOG.md

✅ Yes

Examples

Every feature

docs/source/examples/

✅ ALWAYS

Design Doc

Complex implementation

docs/dev_notes/

⚠️ Optional

Case Study

Demonstrate real-world usage

docs/source/examples/case_studies/

⚠️ Optional but expected
6. Documentation Quality Standards#

User-facing documentation must:

  • ✅ Include runnable code examples

  • ✅ Show expected output

  • ✅ Explain configuration options

  • ✅ Link to related features

  • ✅ Follow single source of truth principle (no duplication)

Design documentation should:

  • ✅ Explain the “why” not just the “what”

  • ✅ Document alternatives considered

  • ✅ Include diagrams for complex flows

  • ✅ Link to related code files

Documentation Validation#

Before submitting a PR with documentation changes:

# Run all documentation checks
make docs-check

# Build and preview locally
make docs-serve
# Visit http://localhost:8000

# Verify no broken links
make docs-validate

# Verify no duplication
make docs-duplication

See docs/DOCUMENTATION_DEPLOYMENT.md for comprehensive testing guide.

📄 License#

By contributing, you agree that your contributions will be licensed under the same Apache License 2.0 that covers the project.

Thank you for contributing to MassGen! 🚀

See Also#

—

Contents