metgrs 社区贡献指南

1. 欢迎贡献

感谢您对 metgrs 项目的关注！我们非常欢迎社区成员的参与和贡献。

metgrs 是一个用于中国地基遥感垂直观测系统数据处理的 Python 库，我们希望：

为气象工作者提供便捷的数据处理工具
构建开放、协作的开源社区
推动气象数据处理技术的发展

无论您是气象专业的研究者、Python 开发者，还是对开源项目感兴趣的爱好者，我们都期待您的参与！

2. 贡献方式

我们欢迎以下形式的贡献：

2.1 代码贡献

Bug 修复：修复现有代码中的错误
新功能开发：添加新的数据读取器、处理算法或可视化方法
性能优化：提升代码运行效率
重构：改进代码结构，提高可维护性

2.2 文档贡献

完善文档：补充缺失的说明、修正错误
添加示例：编写使用教程和示例代码
翻译内容：将文档翻译成其他语言

2.3 社区贡献

问题反馈：报告 Bug、提出改进建议
回答问题：帮助其他用户解决使用问题
代码审查：审查 Pull Request，提供建议
推广宣传：分享项目，吸引更多用户

2.4 数据贡献

测试数据：提供测试用的气象数据样本
设备支持：提供新设备的数据格式文档

3. 开发环境搭建

3.1 克隆仓库

# 克隆项目
git clone https://github.com/longtsing/metgrs.git
cd metgrs

3.2 创建开发环境

# 方式 1：使用 venv + pip
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# 安装开发依赖
pip install -e ".[dev]"

# 方式 2：使用 conda
mamba create -n metgrs-dev python=3.11
mamba activate metgrs-dev
pip install -e ".[dev]"

3.3 安装开发工具

# 代码格式化
pip install black isort

# 代码检查
pip install flake8 mypy

# 测试工具
pip install pytest pytest-cov

# 文档工具
pip install sphinx sphinx-rtd-theme

3.4 运行测试

# 运行所有测试
pytest

# 运行带覆盖率的测试
pytest --cov=metgrs --cov-report=html

# 运行特定测试
pytest tests/test_wind_profile.py

3.5 构建文档

cd docs
make html

4. 代码贡献流程

4.1 Fork 项目

访问 metgrs GitHub 仓库
点击右上角的 “Fork” 按钮
将项目 Fork 到您的 GitHub 账号

4.2 克隆 Fork 的仓库

# 克隆您 Fork 的仓库
git clone https://github.com/YOUR_USERNAME/metgrs.git
cd metgrs

# 添加上游仓库
git remote add upstream https://github.com/longtsing/metgrs.git

3. 创建功能分支

# 同步上游代码
git fetch upstream
git checkout main
git merge upstream/main

# 创建功能分支
git checkout -b feature/your-feature-name

分支命名规范：

feature/xxx：新功能
fix/xxx：Bug 修复
docs/xxx：文档更新
refactor/xxx：代码重构
test/xxx：测试相关

4.4 编写代码

编写您的代码
确保代码符合项目规范
添加必要的测试
更新相关文档

4.5 提交代码

# 添加修改的文件
git add .

# 提交代码
git commit -m "feat: add new feature description"

# 推送到您的 Fork
git push origin feature/your-feature-name

提交信息规范：

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

<body>

<footer>

Type 类型：

feat：新功能
fix：Bug 修复
docs：文档更新
style：代码格式调整（不影响功能）
refactor：代码重构
test：测试相关
chore：构建/工具相关

示例：

feat(wpr): add L2 to L3 wind component synthesis

- Add calc_l2_to_l3() method to WindProfileRadar accessor
- Support multiple beam configurations
- Add unit tests for wind synthesis

Closes #123

4.6 创建 Pull Request

访问您的 Fork 页面
点击 “Compare & pull request”
填写 PR 模板
等待代码审查

5. 代码规范

5.1 Python 代码风格

# 使用 black 格式化代码
black .

# 使用 isort 排序导入
isort .

# 使用 flake8 检查代码
flake8 metgrs/

5.2 代码规范要点

# 1. 使用类型注解
def read_l1_file(filepath: str) -> xr.Dataset:
    """读取 L1 数据文件"""
    pass

# 2. 编写文档字符串
def calculate_wind(data: xr.Dataset, method: str = "mean") -> xr.Dataset:
    """
    计算风场数据
    
    Parameters
    ----------
    data : xr.Dataset
        输入数据集
    method : str, optional
        计算方法，可选 "mean" 或 "median"，默认 "mean"
    
    Returns
    -------
    xr.Dataset
        计算后的风场数据
    
    Examples
    --------
    >>> ds = metgrs.WindProfileRadar.read_l1_file("FFT.BIN")
    >>> wind = calculate_wind(ds, method="mean")
    """
    pass

# 3. 使用有意义的变量名
# 好的命名
wind_speed = data["wind_speed"]
beam_direction = data["beam_direction"]

# 不好的命名
ws = data["ws"]
bd = data["bd"]

# 4. 避免硬编码
# 好的做法
DEFAULT_FILL_VALUE = -999.0
data = data.where(data != DEFAULT_FILL_VALUE)

# 不好的做法
data = data.where(data != -999.0)

5.3 测试规范

# tests/test_wind_profile.py
import pytest
import numpy as np
import metgrs


class TestWindProfileRadar:
    """风廓线雷达测试类"""
    
    def test_read_l1_file(self, sample_l1_file):
        """测试 L1 文件读取"""
        ds = metgrs.WindProfileRadar.read_l1_file(sample_l1_file)
        assert "power_spectrum" in ds.data_vars
        assert ds.dims["range"] > 0
    
    def test_calc_l1_to_l2(self, sample_l1_dataset):
        """测试 L1 到 L2 处理"""
        ds_l2 = sample_l1_dataset.wpr.calc_l1_to_l2()
        assert "radial_velocity" in ds_l2.data_vars
    
    @pytest.mark.parametrize("method", ["mean", "median"])
    def test_wind_calculation_methods(self, sample_data, method):
        """测试不同风场计算方法"""
        result = calculate_wind(sample_data, method=method)
        assert result is not None

6. 社区共享开发模式

6.1 开发理念

metgrs 采用开放协作的开发模式：

核心维护者
    │
    ├─ 负责项目方向和架构设计
    ├─ 审核和合并 Pull Request
    └─ 发布新版本
    
贡献者
    │
    ├─ 提交代码修复和新功能
    ├─ 完善文档和示例
    ├─ 参与问题讨论和代码审查
    └─ 分享使用经验和最佳实践
    
用户
    │
    ├─ 报告问题和提出建议
    ├─ 参与社区讨论
    └─ 推广项目使用

6.2 协作工具

工具	用途	链接
GitHub Issues	问题跟踪和功能请求	Issues
GitHub Discussions	社区讨论和问答	Discussions
Pull Requests	代码贡献和审查	PRs
GitHub Actions	自动化测试和构建	Actions

6.3 开发工作流

1. 选择任务
   │
   ├─ 查看 Issues 列表
   ├─ 选择 "good first issue" 标签的任务（适合新贡献者）
   └─ 评论 Issue 表示您想参与

2. 开发代码
   │
   ├─ Fork 项目
   ├─ 创建功能分支
   └─ 编写代码和测试

3. 提交 PR
   │
   ├─ 填写 PR 模板
   ├─ 关联相关 Issue
   └─ 等待代码审查

4. 代码审查
   │
   ├─ 核心维护者审查代码
   ├─ 根据反馈修改代码
   └─ 获得批准后合并

5. 发布
   │
   ├─ 代码合并到 main 分支
   ├─ 定期发布新版本
   └─ 更新 PyPI 和文档

6.4 模块化开发

metgrs 采用模块化设计，便于多人协作：

metgrs/
├── wind_profile/       # 风廓线仪模块
│   ├── reader.py       # 数据读取
│   ├── processor.py    # 数据处理
│   └── plotter.py      # 可视化
├── cloud_radar/        # 云雷达模块
├── microwave/          # 微波辐射计模块
├── lidar/              # 激光雷达模块
└── utils/              # 通用工具

开发建议：

专注于单个模块：选择您熟悉的设备类型进行开发
保持接口一致：遵循现有的 API 设计模式
独立开发：各模块相对独立，减少冲突
充分测试：为每个模块编写单元测试

6.5 知识共享

我们鼓励社区成员分享：

使用案例：分享 metgrs 在实际工作中的应用
最佳实践：分享数据处理的经验和技巧
教程文档：编写详细的使用教程
问题解决方案：分享遇到的问题和解决方法

7. Issue 和 PR 规范

7.1 Issue 规范

Bug 报告模板

## Bug 描述
简要描述遇到的问题

## 复现步骤
1. 执行 '...'
2. 运行 '...'
3. 看到错误

## 期望行为
描述您期望的行为

## 实际行为
描述实际发生的行为

## 环境信息
- OS: [e.g., Windows 10, Ubuntu 22.04]
- Python: [e.g., 3.11.5]
- metgrs: [e.g., 0.5.3]
- numpy: [e.g., 1.24.0]

## 错误日志

粘贴错误日志

## 附加信息
任何其他相关信息

功能请求模板

## 功能描述
简要描述您希望添加的功能

## 使用场景
描述这个功能的使用场景

## 建议实现方案
如果您有实现建议，请在此描述

## 附加信息
任何其他相关信息

7.2 Pull Request 规范

PR 模板

## 修改内容
简要描述本次修改的内容

## 相关 Issue
Closes #xxx

## 修改类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 文档更新
- [ ] 代码重构
- [ ] 测试添加
- [ ] 其他

## 测试情况
- [ ] 已添加单元测试
- [ ] 已通过现有测试
- [ ] 已手动测试

## 检查清单
- [ ] 代码符合项目规范
- [ ] 已更新相关文档
- [ ] 已添加必要的注释
- [ ] 没有引入新的警告

## 附加信息
任何其他相关信息

8. 代码审查流程

8.1 审查要点

代码审查时，审查者会关注：

功能正确性：代码是否正确实现了预期功能
代码质量：代码是否清晰、可维护
测试覆盖：是否有足够的测试用例
文档更新：是否更新了相关文档
性能影响：是否对性能有负面影响
向后兼容：是否破坏了现有 API

8.2 审查流程

1. 提交 PR
   │
   └─ 自动触发 CI 测试
   
2. 初步审查
   │
   ├─ 检查代码规范
   ├─ 运行测试套件
   └─ 检查文档完整性
   
3. 深入审查
   │
   ├─ 核心维护者审查代码
   ├─ 提出改进建议
   └─ 讨论实现方案
   
4. 修改和完善
   │
   ├─ 根据反馈修改代码
   ├─ 更新测试和文档
   └─ 再次提交审查
   
5. 合并
   │
   ├─ 获得批准
   ├─ 通过所有测试
   └─ 合并到 main 分支

8.3 审查反馈

审查者会使用以下标签：

LGTM：Looks Good To Me，代码看起来很好
Needs Work：需要修改
Question：有疑问需要讨论
Nit：小的改进建议

9. 版本发布流程

9.1 版本号规范

metgrs 使用语义化版本规范：

MAJOR.MINOR.PATCH

MAJOR：不兼容的 API 修改
MINOR：向下兼容的功能性新增
PATCH：向下兼容的问题修正

9.2 发布流程

# 1. 更新版本号
# pyproject.toml
version = "0.6.0"

# 2. 更新 CHANGELOG.md
## [0.6.0] - 2024-xx-xx
### Added
- 新功能 A
- 新功能 B

### Fixed
- 修复 Bug X

### Changed
- 改进 Y

# 3. 创建发布分支
git checkout -b release/0.6.0
git add .
git commit -m "release: v0.6.0"
git tag v0.6.0

# 4. 推送到 GitHub
git push origin release/0.6.0
git push origin v0.6.0

# 5. GitHub Actions 自动构建和发布到 PyPI

9.3 发布周期

Patch 版本：根据需要随时发布（Bug 修复）
Minor 版本：每 1-2 个月发布一次（新功能）
Major 版本：根据重大变更情况发布

10. 社区治理

10.1 角色和职责

角色	职责	权限
核心维护者	项目方向、代码审查、版本发布	仓库写权限
模块维护者	特定模块的开发和维护	模块写权限
贡献者	提交代码、文档、测试	Fork 和 PR 权限
用户	使用项目、反馈问题	只读权限

10.2 决策流程

1. 提出建议
   │
   └─ 通过 Issue 或 Discussion 提出
   
2. 社区讨论
   │
   ├─ 收集反馈意见
   ├─ 讨论实现方案
   └─ 达成共识
   
3. 实施决策
   │
   ├─ 创建相关 Issue
   ├─ 分配任务
   └─ 开始实施
   
4. 评估结果
   │
   ├─ 审查实现
   ├─ 收集反馈
   └─ 必要时调整

10.3 成为核心维护者

如果您希望成为核心维护者，需要：

持续贡献：至少 3 个月的稳定贡献
代码质量：提交高质量的代码和测试
社区参与：积极参与讨论和代码审查
推荐：至少 2 名现有维护者的推荐

11. 行为准则

11.1 我们的承诺

为了营造一个开放、友好的环境，我们承诺：

尊重所有参与者
接受建设性的批评
关注对社区最有利的事情
对他人表示同理心

11.2 不可接受的行为

以下行为是不可接受的：

使用性暗示的语言或图像
人身攻击或侮辱性评论
公开或私下骚扰
未经许可发布他人的私人信息
其他不道德或不专业的行为

11.3 执行

如果发现不可接受的行为，请通过以下方式报告：

邮箱：longtsing@cug.edu.cn
GitHub Issues：私信核心维护者

所有投诉都将被审查和调查，并会做出必要和适当的回应。

联系方式

邮箱：longtsing@cug.edu.cn
GitHub：@longtsing
和鲸社区：longtsing

致谢

感谢所有为 metgrs 做出贡献的开发者！您的贡献使这个项目变得更好。

最后更新：2024 年