贡献指南 (Contributing Guide)

感谢你对 MedTextCN 项目的关注！本文档将帮助你快速了解如何参与项目贡献。

行为准则

请确保你的行为符合开源社区的通用行为准则。尊重每一位贡献者，保持友善和专业的沟通态度。对不同观点保持开放心态，提供建设性的反馈。

环境搭建

前置要求

Python >= 3.9
pip（推荐使用 pip 或 poetry 管理依赖）
Git

克隆仓库

git clone https://github.com/gitstq/MedTextCN.git
cd MedTextCN

创建虚拟环境

# 使用 venv
python -m venv venv
source venv/bin/activate  # Linux / macOS
# 或 venv\Scripts\activate  # Windows

# 或使用 conda
conda create -n medtextcn python=3.9
conda activate medtextcn

安装依赖

pip install -e ".[dev]"

dev 额外依赖包含测试、代码格式化和 lint 工具。

验证安装

python -c "import medtextcn; print(medtextcn.__version__)"

运行测试

pytest tests/ -v

代码规范

Python 代码风格

本项目遵循以下代码规范：

PEP 8：Python 代码风格指南
PEP 257：文档字符串规范
使用 Ruff 进行代码检查和自动格式化（替代 flake8 + isort + black）

格式化命令

# 代码格式化
ruff format .

# 代码检查
ruff check .

# 自动修复可修复的问题
ruff check --fix .

配置文件

项目根目录下的 pyproject.toml 中包含 Ruff 的配置，请确保你的编辑器或 IDE 安装了对应的插件以保持一致的代码风格。

命名规范

类型	规范	示例
模块/包	`snake_case`	`ner_extractor.py`
类名	`PascalCase`	`MedicalNER`
函数/方法	`snake_case`	`extract_entities()`
常量	`UPPER_SNAKE_CASE`	`MAX_TEXT_LENGTH`
私有方法	`_leading_underscore`	`_preprocess_text()`

类型注解

所有公开函数和方法必须包含类型注解：

from typing import List, Dict, Optional

def extract_entities(text: str, entity_types: Optional[List[str]] = None) -> List[Dict[str, str]]:
    """提取文本中的医学实体。"""
    ...

文档字符串

使用 Google 风格的文档字符串：

def process_record(record: Dict[str, str]) -> Dict[str, str]:
    """处理单条病历记录。

    Args:
        record: 包含病历原始数据的字典。
            - text (str): 病历文本内容
            - id (str): 病历唯一标识

    Returns:
        包含处理结果的字典，包含结构化字段。

    Raises:
        ValueError: 当 record 格式不合法时抛出。
    """
    ...

导入顺序

遵循以下导入顺序（Ruff isort 自动处理）：

标准库
第三方库
本地模块

每组之间空一行。

提交规范

本项目采用 Angular 提交规范 (Angular Commit Convention)。

提交消息格式

<type>(<scope>): <subject>

<body>

<footer>

Type（类型）

类型	说明
`feat`	新功能
`fix`	修复 Bug
`docs`	文档变更
`style`	代码格式（不影响功能）
`refactor`	重构（既非新功能也非修复）
`perf`	性能优化
`test`	测试相关
`chore`	构建过程或辅助工具变动
`ci`	CI/CD 配置变更
`build`	构建系统或外部依赖变更

Scope（范围）

可选，表示影响范围，例如：

ner — 命名实体识别模块
pii — 隐私信息脱敏模块
struct — 病历结构化模块
core — 核心模块
cli — 命令行工具

Subject（主题）

简短描述，不超过 50 个字符
使用祈使句，如 "add" 而非 "added"
首字母小写
末尾不加句号

示例

git commit -m "feat(ner): add support for disease entity recognition"
git commit -m "fix(pii): handle empty text in de-identification pipeline"
git commit -m "docs: update README installation instructions"
git commit -m "test(struct): add unit tests for record parser"
git commit -m "refactor(core): extract common preprocessing utilities"

提交消息工具

推荐使用 commitizen 或 cz 工具辅助生成规范的提交消息：

pip install commitizen
cz commit

Pull Request 流程

1. Fork 仓库

点击 GitHub 页面右上角的 Fork 按钮，将仓库 Fork 到你的个人账号下。

2. 创建分支

git checkout -b feat/your-feature-name
# 或
git checkout -b fix/your-bug-fix-name

分支命名建议：

类型	格式	示例
新功能	`feat/<简短描述>`	`feat/add-drug-ner`
修复	`fix/<简短描述>`	`fix/encoding-error`
文档	`docs/<简短描述>`	`docs/api-reference`
重构	`refactor/<简短描述>`	`refactor/split-modules`

3. 进行开发

遵循上述代码规范
为新功能编写对应的单元测试
确保所有测试通过：pytest tests/ -v
运行代码检查：ruff check .

4. 提交变更

使用 Angular 提交规范提交你的变更。

5. 推送分支

git push origin feat/your-feature-name

6. 创建 Pull Request

访问你 Fork 的仓库页面
点击 "New Pull Request"
选择你的分支作为源分支，gitstq/MedTextCN 的 main 分支作为目标分支
填写 PR 描述，包含以下内容：
- 变更说明：做了什么，为什么做
- 关联 Issue：Fixes #<issue_number> 或 Closes #<issue_number>
- 测试说明：如何验证变更
- 截图/日志（如适用）

7. PR 审查

维护者会在合理时间内审查你的 PR
请及时回复审查意见
如果需要修改，请在同一分支上追加提交

8. 合并

PR 通过审查且 CI 全部通过后，由维护者合并
合并策略通常采用 Squash Merge，保持提交历史整洁

Issue 指南

提交 Bug 报告

请使用仓库中的 Bug Report 模板提交 Issue，确保包含：

问题描述
复现步骤
期望行为
实际行为
环境信息（Python 版本、操作系统等）
日志或错误信息

提交功能请求

请使用仓库中的 Feature Request 模板提交功能请求，包含：

功能描述
使用场景
期望的行为
可能的实现方案（如有）

许可证

贡献的代码将采用项目的 MIT License 许可证。提交 PR 即表示你同意你的贡献将在该许可证下发布。

感谢你的贡献！每一个 PR、Issue 和建议都是对项目的宝贵支持。

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History