deer-flow/docs/LICENSE_HEADERS.md

License Header Management

This document explains how to manage license headers in the DeerFlow project.

License Header Format

All source files in this project should include license headers.

Python Files

# Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
# SPDX-License-Identifier: MIT

For files with a shebang (#!/usr/bin/env python3), the header is placed after the shebang:

#!/usr/bin/env python3
# Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
# SPDX-License-Identifier: MIT

import something

TypeScript Files

// Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
// SPDX-License-Identifier: MIT

import { something } from "somewhere";

Makefile Targets

Check License Headers

Check if all Python and TypeScript files have the required license header:

# Check all files (Python and TypeScript)
make check-license-all

# Check only Python files
make check-license

# Check only TypeScript files
make check-license-ts

These commands:

• Scan all source files in src/, tests/, web/src/, web/tests/, and root-level files
• Report files missing the license header
• Return exit code 1 if any files are missing headers (useful for CI/CD)
• Return exit code 0 if all files have headers

Add License Headers

Automatically add license headers to files that don't have them:

# Add to all files (Python and TypeScript)
make add-license-all

# Add only to Python files
make add-license

# Add only to TypeScript files
make add-license-ts

These commands:

• Add the appropriate license header to files that don't have it
• Preserve shebangs at the top of Python files
• Add appropriate spacing after headers
• Show vTypeScript files uv run python scripts/license_header.py web/src/components/ --check

Check a single file (works for both .py and .ts/.tsx)

uv run python scripts/license_header.py src/workflow.py --check uv run python scripts/license_header.py web/src/core/api/chat.ts --check

### Script Options

- `--check`: Check mode - verify headers without modifying files
- `--verbose` / `-v`: Show detailed output for each file processed
- `paths`: One or more paths (files or directories) to process

### Supported File Types

The script automatically detects and processes:
- Python files (`.py`)
- TypeScript files (`.ts`)
- TypeScript React files (`.tsx`)

## Pre-commit Hook

The license header check is integrated into the pre-commit hook. Before allowing a commit, it will:

1. Run linting (`make lint`)
2. Run formatting (`make format`)

This ensures all merged code has proper license headers for both Python and TypeScript fileill be blocked. Run `make add-license` to fix.

## CI/CD Integration

For continuous integration, add the license check to your workflow:

```bash
# In your CI script or GitHub Actions
ma`.next` (Next.js build directory)
- ke check-license

This ensures all merged code has proper license headers.

Files Excluded

The license header tool automatically skips:

• __pycache__ directories
• .pytest_cache, .ruff_cache, .mypy_cache
• node_modules
• Virtual environment directories (.venv, venv, .tox)
• Build artifacts (build, dist)
• .git directory

Customization

Changing the License Header

Sdictionary inscripts/license_header.py`:

LICENSE_HEADERS: Dict[str, str] = {
    "python": """# Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
# SPDX-License-Identifier: MIT
""",
    "typescript": """// Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
// SPDX-License-Identifier: MIT
""",
}

Adding Mo-all:

@uv run python scripts/license_header.py src/ tests/ scripts/ web/src/ web/test

1. Add the extension to FILE_TYPE_MAP in scripts/license_header.py
2. Add the corresponding header format to LICENSE_HEADERS

FILE_TYPE_MAP = {
    ".py": "python",
    ".ts": "typescript",
    ".tsx": "typescript",
    ".js": "javascript",  # Example: adding JavaScript support
}

LICENSE_HEADERS = {
    # ... existing headers ...
    "javascript": """// Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
// SPDX-License-Identifier: MIT
""",
}PDX-License-Identifier: MIT
"""

-all Checking license headers in all source files... ✅ All 289 source file(s) have license headers.

### Example 2: Check Only TypeScript Files
```bash
$ make check-license-ts
Checking license headers in TypeScript files...
❌ 3 file(s) missing license header:
  - web/src/components/new-component.tsx
  - web/src/core/api/new-api.ts
  - web/tests/new-test.test.ts

Run 'make add-license-ts' to add headers.

Example 3: Add Headers to New Module

$ make add-license-all
Adding license headers to all source files...
✅ Added license header to 11 file(s).

Example 4: Check Specific Directory

$ uv run python scripts/license_header.py web/src/components/ --check --verbose
Header already present: web/src/components/deer-flow/logo.tsx
Header already present: web/src/components/deer-flow/markdown.tsx
Header already present: web/src/components/editor/index.tsx
✅ All 24 sourceooks for exact matches (ignoring leading/trailing whitespace)

### "Pre-commit hook blocks my commit"
- Run `make add-license` to add headers to all files
- Or disable the check temporarily by editing the `pre-commit` file

## Examples

### Example 1: Check All Files
```bash
$ make check-license
Checking license headers in Python files...
✅ All 156 Python file(s) have license headers.

Example 2: Add Headers to New Module

$ make add-license
Adding license headers to Python files...
✅ Added license header to 11 file(s).

Example 3: Check Specific Directory

$ uv run python scripts/license_header.py src/agents/ --check --verbose
Header already present: src/agents/base.py
Header already present: src/agents/coordinator.py
✅ All 8 Python file(s) have license headers.