Skip to main content
欢迎贡献代码！无论您是修复错误、添加新功能还是提升性能，您的贡献都将帮助为所有开发者提供更佳的体验。
在提交大型新功能或重构之前，请先在论坛中讨论您的想法。这有助于确保与项目目标保持一致，并避免重复工作。此要求不适用于错误修复或小型改进，您可以直接通过拉取请求（Pull Request）进行贡献。请务必在您的 PR 描述中链接相关的问题。使用，以便在 PR 合并时自动关闭对应的问题。新的集成应遵循集成指南。

​
哲学理念

所有代码贡献都应力求遵循以下核心原则：

向后兼容性

保持稳定的公共接口，避免破坏性变更

测试先行

每项变更都必须包含全面的测试，以验证正确性并防止功能倒退

代码质量

遵循一致的代码风格、文档规范和架构模式

注重安全

优先考虑安全编码实践，预防漏洞

​
快速入门

​
快速修复：提交一个错误修复

对于简单的错误修复，您可以立即开始：
1

克隆并设置环境

git clone https://github.com/your-username/name-of-forked-repo.git

# 例如，对于 LangChain：
git clone https://github.com/parrot123/langchain.git

# 对于 LangGraph：
git clone https://github.com/parrot123/langgraph.git

# 在您的仓库内，安装依赖项
uv sync --all-groups
2

创建分支

git checkout -b your-username/short-bugfix-name
3

进行修改

在修复错误时，请遵循我们的 代码质量标准
4

添加测试

包含在没有您的修复时会失败的 单元测试。这使我们能够验证错误已解决并防止功能倒退
5

运行测试

在提交 PR 之前，请确保所有测试在本地通过
make lint
make test

# 对于涉及集成的错误修复，还需运行：
make integration_tests
6

提交拉取请求（PR）

请遵循提供的 PR 模板。如果适用，请使用 关闭关键词（例如 Fixes #123）引用您正在修复的问题。

​
完整的开发设置

对于持续开发或较大贡献：
1

开发环境

按照我们的设置指南配置您的环境
2

仓库结构

了解仓库结构和包组织方式
3

开发工作流程

学习我们的开发工作流程，包括测试和代码检查
4

贡献指南

查阅我们的贡献指南，了解功能、错误修复和集成的相关要求

​
开发环境

为你正在开发的包设置开发环境：
  • LangChain
  • LangGraph
For changes to langchain-core:
cd libs/core
uv sync --all-groups
make test  # Ensure tests pass before starting development
For changes to langchain:
cd libs/langchain
uv sync --all-groups
make test  # Ensure tests pass before starting development
For changes to partner integrations:
cd libs/partners/langchain-{partner}
make test  # Ensure tests pass before starting development
For changes to community integrations (located in a separate repo):
cd libs/community/langchain_community/path/to/integration
make test  # Ensure tests pass before starting development

​
仓库结构

  • LangChain
  • LangGraph
LangChain 采用单体仓库（monorepo）结构，包含多个包：
  • langchain-core（位于 libs/core/）：基础接口与核心抽象
  • langchain（位于 libs/langchain/）：包含链（chains）、代理（agents）和检索逻辑的主包
位于 libs/partners/，这些是为特定集成独立版本管理的包。例如：许多合作伙伴包位于外部仓库中。详情请参阅 集成列表。

​
开发工作流程

​
测试要求

目录路径均相对于您当前正在开发的软件包。
每次代码变更都必须包含全面的测试。
1

Unit tests

Location: tests/unit_tests/需求:
  • 禁止进行网络调用
  • 测试所有代码路径，包括边界情况
  • 对外部依赖使用模拟（mock）
make test
# 或者直接运行：
uv run --group test pytest tests/unit_tests
2

Integration tests

集成测试需要访问外部服务或供应商 API（可能产生费用），因此默认不会运行。并非每次代码变更都需要编写集成测试，但请注意，我们将在代码审查过程中单独要求并运行集成测试。Location: tests/integration_tests/Requirements:
  • 测试与外部服务的真实集成
  • 使用环境变量管理 API 密钥
  • 若凭据不可用，应优雅跳过
make integration_tests
3

测试质量检查清单

  • 代码出错时测试应失败
  • 已测试边界情况和错误条件
  • 正确使用 fixtures 和 mocks

​
Code quality standards

Quality requirements:
  • Type hints
  • Documentation
  • Code style
Required: Complete type annotations for all functions
def process_documents(
    docs: list[Document],
    processor: DocumentProcessor,
    *,
    batch_size: int = 100
) -> ProcessingResult:
    """Process documents in batches.

    Args:
        docs: List of documents to process.
        processor: Document processing instance.
        batch_size: Number of documents per batch.

    Returns:
        Processing results with success/failure counts.
    """

​
Manual formatting and linting

Code formatting and linting are enforced via CI/CD. Run these commands before committing to ensure your code passes checks.
Run formatting and linting:
1

Format code

make format
2

Run linting checks

make lint
3

Verify changes

Both commands will show you any formatting or linting issues that need to be addressed before committing.

​
Contribution guidelines

​
Backwards compatibility

Breaking changes to public APIs are not allowed except for critical security fixes.See our versioning policy for details on major version releases.
Maintain compatibility:
Always preserve:
  • Function signatures and parameter names
  • Class interfaces and method names
  • Return value structure and types
  • Import paths for public APIs
Acceptable modifications:
  • Adding new optional parameters
  • Adding new methods to classes
  • Improving performance without changing behavior
  • Adding new modules or functions
  • Would this break existing user code?
  • Check if your target is public
  • If needed, is it exported in __init__.py?
  • Are there existing usage patterns in tests?

​
Bugfixes

For bugfix contributions:
1

Reproduce the issue

Create a minimal test case that demonstrates the bug. Maintainers and other contributors should be able to run this test and see the failure without additional setup or modification
2

Write failing tests

Add unit tests that would fail without your fix
3

Implement the fix

Make the minimal change necessary to resolve the issue
4

Verify the fix

Ensure that tests pass and no regressions are introduced
5

Document the change

Update docstrings if behavior changes, add comments for complex logic

​
New features

We aim to keep the bar high for new features. We generally don’t accept new core abstractions, changes to infra, changes to dependencies, or new agents/chains from outside contributors without an existing issue that demonstrates an acute need for them. In general, feature contribution requirements include:
1

Design discussion

Open an issue describing:
  • The problem you’re solving
  • Proposed API design
  • Expected usage patterns
2

Implementation

  • Follow existing code patterns
  • Include comprehensive tests and documentation
  • Consider security implications
3

Integration considerations

  • How does this interact with existing features?
  • Are there performance implications?
  • Does this introduce new dependencies?
We will reject features that are likely to lead to security vulnerabilities or reports.

​
Security guidelines

Security is paramount. Never introduce vulnerabilities or unsafe patterns.
Security checklist:
  • Validate and sanitize all user inputs
  • Properly escape data in templates and queries
  • Never use eval(), exec(), or pickle on user data, as this can lead to arbitrary code execution vulnerabilities
  • Use specific exception types
  • Don’t expose sensitive information in error messages
  • Implement proper resource cleanup
  • Avoid adding hard dependencies
  • Keep optional dependencies minimal
  • Review third-party packages for security issues

​
Testing and validation

​
Running tests locally

Before submitting your PR, ensure you have completed the following steps. Note that the requirements differ slightly between LangChain and LangGraph.
  • LangChain
  • LangGraph
1

Unit tests

make test
All unit tests must pass
2

Integration tests

make integration_tests
(Run if your changes affect integrations)
3

Formatting

make format
make lint
Code must pass all style checks
4

Type checking

make type_check
All type hints must be valid
5

PR submission

Push your branch and open a pull request. Follow the provided form template. Note related issues using a closing keyword. After submitting, wait, and check to ensure the CI checks pass. If any checks fail, address the issues promptly - maintainers may close PRs that do not pass CI within a reasonable timeframe.

​
Test writing guidelines

In order to write effective tests, there’s a few good practices to follow:
  • Use natural language to describe the test in docstrings
  • Use descriptive variable names
  • Be exhaustive with assertions
  • Unit tests
  • Integration tests
  • Mock usage
def test_document_processor_handles_empty_input():
    """Test processor gracefully handles empty document list."""
    processor = DocumentProcessor()

    result = processor.process([])

    assert result.success
    assert result.processed_count == 0
    assert len(result.errors) == 0

​
Getting help

Our goal is to have the simplest developer setup possible. Should you experience any difficulty getting setup, please ask in the community slack or open a forum post.
You’re now ready to contribute high-quality code to LangChain!