Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
392 lines (282 loc) · 11.3 KB

CONTRIBUTING.md

File metadata and controls

392 lines (282 loc) · 11.3 KB
Raw

🌟 贡献指南

中文 | English

欢迎来到公开气象数据资源库！感谢你愿意为这个项目贡献一份力量。本指南将帮助你了解如何为项目做出贡献。

📄 许可协议：本项目采用 MIT License 开源，提交贡献即表示你同意在 MIT 协议下发布你的内容。请注意：MIT 仅覆盖本仓库自身的内容与代码，所列第三方数据源各有独立许可，贡献时请勿引入违反其条款的内容。

📋 目录

行为准则

参与本项目，请遵守我们的行为准则：

  • 🤝 尊重他人：保持友好和专业的交流氛围
  • 📚 乐于助人：帮助新成员熟悉项目
  • 🔍 严谨认真：确保提交的数据准确可靠
  • 📄 遵守协议：尊重数据提供方的使用条款
  • 🌐 开放包容：欢迎来自不同背景的贡献者

如何贡献

报告问题

如果你发现以下问题，请通过 Issues 页面报告：

  • 🔗 链接失效：数据链接无法访问
  • 📊 信息过时：数据源信息需要更新
  • ❌ 数据错误：数据描述或分类不正确
  • 💡 功能建议：对项目改进的建议
  • ➕ 资源推荐：推荐新的数据源

问题报告模板：

## 问题类型
[ ] 链接失效 [ ] 信息过时 [ ] 数据错误 [ ] 功能建议 [ ] 资源推荐

## 描述
<!-- 详细描述问题 -->

## 受影响的部分
<!-- 如果是链接失效或数据错误，请指明具体位置 -->

## 建议解决方案（可选）
<!-- 如果有解决方案建议，请在此说明 -->

## 环境信息
- 操作系统：
- 浏览器：
- 发现时间：

添加新数据源

添加新数据源时，请确保：

  1. 数据可公开访问：无需注册或付费即可访问
  2. 来源可靠：来自官方或知名机构
  3. 格式规范：按照现有分类和折叠卡片格式添加
  4. 信息完整：包含所有必需徽章和链接

数据源添加模板：

<details>
<summary><b>数据名称</b> · 机构/简短描述</summary>

![分辨率](https://img.shields.io/badge/分辨率-0.25°-blue?style=flat-square)
![时效](https://img.shields.io/badge/时效-0~384h(3h)-green?style=flat-square)
![更新](https://img.shields.io/badge/更新-每日4次-orange?style=flat-square)
![来源](https://img.shields.io/badge/来源-数据提供方-颜色代码?style=flat-square)

🔗 [数据链接](https://example.com/data) · 📅 数据时段 · 📝 [示例代码](./sources/example.py)

</details>

💡 OPeNDAP / THREDDS 数据源：裸 OPeNDAP URL 在浏览器直接打开会返回 HTTP 400，请改用「可浏览目录 + OPeNDAP 代码」格式：

🔗 📂 [目录](https://psl.noaa.gov/thredds/catalog/Datasets/xxx/catalog.html) · OPeNDAP `https://.../dodsC/Datasets/xxx/file.nc` · 📝 [下载脚本](./sources/download_from_opendap.py)

🔎 提交前务必验证链接可达：将候选 URL 写入文件后运行 bash test_codes/check_readme_links.sh test_codes/_candidates_xxx.txt，仅保留 ✅ 的源。

徽章颜色规范：

来源类型 颜色代码 示例
官方机构 9CF CMA, DWD, JMA
NOAA 00CED1 NOAA, NCEP
NASA FF0000 NASA, MERRA-2
UCAR 800080 UCAR, NCAR
ECMWF/CDS 00CED1 ECMWF, CDS
ESA/Copernicus 003399 ESA, Copernicus
AWS FF9900 AWS S3
Google 4285F4 Google Cloud
OpeNDAP 00BFFF OpeNDAP 服务
其他 00BFFF 其他数据提供方

徽章字段说明：

徽章 用途 适用数据类型
分辨率 空间分辨率 格点数据
时效 预报时效范围 预报数据
更新 数据更新频率 所有数据
来源 数据提供方 所有数据
时间分辨率 时间间隔 再分析/观测数据
时间范围 历史数据覆盖 历史数据
魔法 需要特殊网络 需VPN访问
类型 数据类型 气候/观测数据

改进文档

欢迎改进项目文档，包括：

  • ✏️ 修正错别字和语法错误
  • 🎨 改进文档结构和可读性
  • 🔧 完善使用说明和示例
  • 🌍 添加多语言翻译

提交代码

如果你有编程技能，可以贡献：

  • 🛠️ 数据处理脚本
  • 📊 数据验证工具
  • 🔗 API 封装库
  • 🧪 测试用例

贡献流程

1. Fork 项目仓库

  1. 点击 GitHub 页面右上角的 "Fork" 按钮
  2. 将项目克隆到本地：
git clone https://github.com/wait4xx/open-earth-data-guide.git
cd open-earth-data-guide

2. 创建分支

为你的贡献创建功能分支：

git checkout -b feature/your-feature-name

分支命名约定：

  • feature/data-source-name - 添加新数据源
  • fix/issue-description - 修复问题
  • docs/topic - 文档改进

3. 进行修改

在本地进行修改，确保：

  • 遵循项目的代码和文档规范
  • 测试所有链接的有效性
  • 更新相关的文档

4. 提交更改

使用描述性的提交信息：

git add .
git commit -m "feat: 添加中国气象局全球模式数据源"

提交信息格式：

  • feat: 新功能或数据源
  • fix: 修复问题
  • docs: 文档更新
  • style: 格式调整
  • refactor: 代码重构

5. 推送并创建 Pull Request

git push origin feature/your-feature-name

然后在 GitHub 上创建 Pull Request，并填写 PR 模板。

数据源标准

可接受的数据源

✅ 官方气象机构：WMO成员机构、国家气象局等 ✅ 科研机构：大学、研究所的公开数据 ✅ 政府开放数据：政府发布的免费气象数据 ✅ 国际组织：联合国、世界银行等机构数据 ✅ 社区项目：有良好维护的开源气象项目

不可接受的数据源

❌ 商业数据：需要付费订阅的数据 ❌ 限制性数据：有严格使用限制的数据 ❌ 个人博客：非官方、未经验证的数据源 ❌ 侵权内容：侵犯版权或协议的数据

数据质量要求

  • 可访问性：链接稳定，无需特殊权限
  • 时效性：数据定期更新
  • 完整性：提供元数据和文档
  • 准确性：数据来源可靠准确

文档规范

Markdown 格式

  • 使用标准的 Markdown 语法
  • 使用 <details> 标签创建可折叠卡片
  • 链接使用描述性文字 🔗 [描述](URL)
  • 图片添加替代文本 ![描述](image-url)
  • 使用 shields.io 徽章展示元数据

徽章格式

所有数据源条目应使用徽章展示关键信息：

![标签](https://img.shields.io/badge/标签-值-颜色?style=flat-square)

颜色含义：

  • blue - 空间分辨率等基础信息
  • green - 时效、时间分辨率等时间信息
  • orange - 更新频率、时间范围等
  • 自定义颜色 - 数据来源标识

数据卡片结构

每个数据源应包含以下结构：

<details>
<summary><b>数据名称</b> · 简短描述</summary>

<!-- 可选：重要提示 -->
***重要说明（如有）***

---

**子类型名称** · 可选描述

![徽章1](...)
![徽章2](...)
![徽章3](...)
![来源](...)

🔗 [链接名称](URL) · 📅 数据时段 · 📝 [示例](./path) · ⚠️ 注意事项

---

**另一个子类型**

...

</details>

链接图标说明

图标 含义 示例
🔗 数据链接 🔗 GFS_NOAA
📅 数据时段 📅 最近 10 日
📝 示例代码/文档 📝 Python示例
⚠️ 注意事项 ⚠️ 需登录
🔄 数据状态 🔄 近实时
🪜 需特殊网络 🪜 需VPN访问
🔍 搜索提示 🔍 搜索关键词

数据字段要求

字段 必需 描述 示例
数据名称 是 数据产品或服务的名称 GFS 全球预报系统
机构 是 数据提供机构（在summary中） NOAA/NCEP
分辨率 是 空间分辨率（徽章） 0.25°
时间信息 是 时效或时间分辨率（徽章） 0~384h(3h)
更新频率 是 数据更新频率（徽章） 每日4次
来源 是 数据提供方（徽章） NOAA
链接 是 数据获取链接 NOMADS
数据时段 推荐 历史数据覆盖范围 📅 2021年至今

代码规范

Python 代码

# 使用明确的变量名
data_url = "https://example.com/data"
max_retry_attempts = 3

# 添加类型提示
def download_data(url: str, timeout: int = 30) -> bytes:
    """下载数据的函数说明
    
    Args:
        url: 数据下载链接
        timeout: 超时时间（秒）
    
    Returns:
        下载的二进制数据
        
    Raises:
        ConnectionError: 当连接失败时抛出
    """
    pass

Shell 脚本

#!/bin/bash

# 脚本描述
# 用法: ./script.sh <参数>

set -euo pipefail  # 严格模式

readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

评审流程

Pull Request 检查清单

在提交 PR 前，请确认：

  • 代码/文档遵循项目规范
  • 所有链接有效且可访问
  • 数据源使用折叠卡片格式（<details>）
  • 包含所有必需徽章（分辨率、时效、更新、来源）
  • 来源徽章使用正确的颜色代码
  • 添加了必要的测试（如适用）
  • 更新了相关文档
  • 提交信息清晰明确
  • 分支与主分支无冲突

评审标准

  1. 功能性：贡献解决了什么问题
  2. 质量：代码/文档质量是否符合标准
  3. 测试：是否包含适当的测试用例
  4. 文档：是否更新了相关文档
  5. 兼容性：是否与现有内容兼容

社区交流

讨论渠道

  • 💬 GitHub Discussions：用于功能讨论和问题咨询
  • 🐛 GitHub Issues：用于报告问题和建议功能
  • 📧 邮件列表：用于重要公告和讨论

获取帮助

如果你在贡献过程中遇到困难：

  1. 首先查看文档和现有 Issues
  2. 在 Discussions 中提问
  3. 联系维护者

成为维护者

长期活跃的贡献者可以申请成为项目维护者，职责包括：

  • 评审和合并 Pull Request
  • 管理 Issues 和 Discussions
  • 指导新贡献者
  • 制定项目发展方向

感谢你阅读本贡献指南！我们期待你的贡献，共同建设更好的气象数据资源社区。🎉

如果有任何问题，请随时通过 Issues 联系我们。