Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
231 lines (168 loc) · 6.53 KB

CONTRIBUTING.md

File metadata and controls

231 lines (168 loc) · 6.53 KB

Contributing to Druid | 贡献指南

English | 中文

English

Thank you for your interest in contributing to Druid! This guide will help you get started.

Code of Conduct

Please be respectful and constructive in all interactions. We are committed to providing a welcoming and inclusive experience for everyone.

How to Contribute

Reporting Bugs

  1. Search existing issues to check if the bug has already been reported
  2. If not, create a new issue with:
    • A clear, descriptive title
    • Steps to reproduce the problem
    • Expected behavior vs actual behavior
    • Druid version, Java version, and database type
    • Relevant logs or stack traces

Suggesting Features

Open a GitHub Issue describing:

  • The use case and motivation
  • Expected behavior
  • Example code or configuration (if applicable)

Submitting Code Changes

  1. Fork the repository and create your branch from master
  2. Write code following our conventions (see below)
  3. Add tests for any new functionality
  4. Run the test suite to verify nothing is broken
  5. Submit a Pull Request with a clear description

Development Setup

Prerequisites

  • Java 8+ JDK
  • Apache Maven 3.6+
  • Git

Building

git clone https://github.com/alibaba/druid.git
cd druid
mvn clean install

Running Tests

# Run all tests
mvn test

# Run tests for a specific module
mvn test -pl core

# Run a specific test class
mvn test -pl core -Dtest=com.alibaba.druid.bvt.sql.mysql.MySqlSelectTest

Code Conventions

  • Language: Java 8+ compatible
  • Style: Follow the project's Checkstyle rules (src/checkstyle/druid-checks.xml)
  • Testing: All new features must include tests in the corresponding bvt (Black-box Verification Test) package
  • SQL Dialect Tests: Use the resource-driven test pattern with .txt files in core/src/test/resources/bvt/parser/<dialect>/

Project Structure

core/src/main/java/com/alibaba/druid/
├── pool/            # Connection pool implementation
├── sql/
│   ├── ast/         # SQL AST node classes
│   ├── dialect/     # Dialect-specific parsers and visitors
│   ├── parser/      # Core parser infrastructure
│   └── visitor/     # AST visitor interfaces
├── filter/          # Filter-Chain implementations
├── stat/            # Monitoring and statistics
├── wall/            # SQL firewall (WallFilter)
└── util/            # Utility classes

Adding a New SQL Dialect

If you want to add support for a new database dialect:

  1. Create the dialect package: sql/dialect/<name>/
  2. Implement these classes:
    • <Name>Lexer - Lexical analyzer with dialect-specific keywords
    • <Name>ExprParser - Expression parser
    • <Name>StatementParser - Statement parser
    • <Name>SelectParser - SELECT statement parser (if needed)
    • <Name>OutputVisitor - SQL output/generation visitor
    • <Name>ASTVisitor - AST visitor interface
    • <Name>SchemaStatVisitor - Schema statistics visitor
  3. Register the dialect in SQLParserUtils and SQLUtils
  4. Add dialect configuration in META-INF/druid/parser/<name>/:
    • dialect.properties - Quote characters and other settings
    • builtin_datatypes - Supported data types
  5. Add comprehensive tests

Pull Request Guidelines

  • Keep PRs focused — one feature or fix per PR
  • Include tests for new functionality
  • Update documentation if behavior changes
  • Write clear commit messages in English
  • Reference related issues in the PR description

Review Process

  1. A maintainer will review your PR
  2. Address any requested changes
  3. Once approved, your PR will be merged

中文

感谢你对 Druid 项目的关注！本指南将帮助你快速参与到项目开发中。

行为准则

请在所有交流中保持尊重和建设性态度。

如何贡献

报告 Bug

  1. 先搜索已有 Issue，确认是否已被报告
  2. 如果没有，创建新 Issue，包含：
    • 清晰的标题
    • 复现步骤
    • 期望行为与实际行为
    • Druid 版本、Java 版本、数据库类型
    • 相关日志或堆栈信息

建议新功能

提交 GitHub Issue，描述：

  • 使用场景和动机
  • 期望的行为
  • 示例代码或配置（如适用）

提交代码

  1. Fork 仓库，基于 master 创建分支
  2. 按照代码规范编写代码
  3. 为新功能添加测试
  4. 运行测试确保没有破坏现有功能
  5. 提交 Pull Request，附上清晰的描述

开发环境

前提条件

  • Java 8+ JDK
  • Apache Maven 3.6+
  • Git

构建

git clone https://github.com/alibaba/druid.git
cd druid
mvn clean install

运行测试

# 运行所有测试
mvn test

# 运行特定模块的测试
mvn test -pl core

# 运行特定测试类
mvn test -pl core -Dtest=com.alibaba.druid.bvt.sql.mysql.MySqlSelectTest

代码规范

  • 语言： 兼容 Java 8+
  • 风格： 遵循项目的 Checkstyle 规则（src/checkstyle/druid-checks.xml）
  • 测试： 所有新功能必须在 bvt（黑盒验证测试）包中添加对应测试
  • SQL 方言测试： 使用 core/src/test/resources/bvt/parser/<dialect>/ 下的 .txt 资源驱动测试

添加新的 SQL 方言

如果要添加新的数据库方言支持：

  1. 创建方言包：sql/dialect/<name>/
  2. 实现以下类：
    • <Name>Lexer - 词法分析器（含方言特有关键字）
    • <Name>ExprParser - 表达式解析器
    • <Name>StatementParser - 语句解析器
    • <Name>SelectParser - SELECT 解析器（如需要）
    • <Name>OutputVisitor - SQL 输出访问者
    • <Name>ASTVisitor - AST 访问者接口
    • <Name>SchemaStatVisitor - Schema 统计访问者
  3. 在 SQLParserUtils 和 SQLUtils 中注册方言
  4. 在 META-INF/druid/parser/<name>/ 添加配置：
    • dialect.properties - 引号字符等设置
    • builtin_datatypes - 支持的数据类型
  5. 添加完整的测试用例

Pull Request 规范

  • 保持 PR 聚焦 — 每个 PR 只包含一个功能或修复
  • 新功能必须包含测试
  • 行为变更需更新文档
  • 使用英文编写清晰的 commit message
  • 在 PR 描述中引用相关 Issue

审核流程

  1. 维护者将审核你的 PR
  2. 根据反馈进行修改
  3. 审核通过后合并