Four Keys开发指南：如何贡献代码和扩展解析器

Four Keys开发指南：如何贡献代码和扩展解析器

【免费下载链接】fourkeysPlatform for monitoring the four key software delivery metrics of software delivery项目地址: https://gitcode.com/gh_mirrors/fo/fourkeys

Four Keys是一个用于监控软件交付四大关键指标的平台，通过它你可以轻松追踪部署频率、变更前置时间、变更失败率和服务恢复时间等关键指标。本指南将带你了解如何为这个开源项目贡献代码以及扩展自定义解析器，即使你是新手也能快速上手。

项目架构概览

Four Keys采用模块化设计，主要由事件处理、数据解析和指标展示三大核心部分组成。事件从各种来源（如GitHub、GitLab等）流入系统，经过解析器处理后存储到BigQuery，最终通过仪表盘展示关键指标。

核心工作流程

1. 事件收集：通过Event Handler接收各类软件交付事件
2. 数据处理：Pub/Sub系统分发事件到相应的Data Parsers
3. 数据存储：解析后的数据存储到BigQuery
4. 指标展示：通过Grafana仪表盘展示四大关键指标

贡献代码的准备工作

环境搭建

首先需要将项目仓库克隆到本地：

git clone https://gitcode.com/gh_mirrors/fo/fourkeys cd fourkeys

项目使用Python开发，建议使用虚拟环境进行开发：

python -m venv venv source venv/bin/activate # Linux/Mac # 或在Windows上使用: venv\Scripts\activate pip install -r requirements-test.txt

贡献规范

在提交代码前，请确保遵循以下规范：

• 所有代码提交前必须通过测试
• 使用GitHub Pull Request进行代码提交
• 提交前签署Contributor License Agreement (CLA)
• 遵循Google的开源社区准则

详细贡献指南可参考项目根目录下的CONTRIBUTING.md文件。

扩展自定义解析器

解析器工作原理

解析器是Four Keys的核心组件，负责将不同来源的原始事件数据转换为统一格式。项目已内置多种解析器，如GitHub、GitLab、CircleCI等，你可以在bq-workers/目录下找到这些解析器的实现。

使用模板创建新解析器

项目提供了便捷的解析器模板，位于bq-workers/new-source-template/目录。只需复制该模板并修改相应部分即可创建新的解析器：

cp -r bq-workers/new-source-template/ bq-workers/your-source-parser/

解析器开发步骤

1. 修改main.py文件：主要需要实现process_new_source_event函数，该函数负责解析原始事件数据

def process_new_source_event(msg): metadata = json.loads(base64.b64decode(msg["data"]).decode("utf-8").strip()) # 解析metadata并映射到标准事件格式 new_source_event = { "event_type": "push", # 事件类型，如"push"、"pull_request"等 "id": metadata.get("id"), # 事件唯一ID "metadata": json.dumps(metadata), # 原始元数据 "time_created": metadata.get("timestamp"), # 事件创建时间戳 "signature": generate_signature(metadata), # 生成事件唯一签名 "msg_id": msg["message_id"], # Pub/Sub消息ID "source": "your-source", # 来源名称，如"gitlab"、"jenkins"等 } return new_source_event

2. 添加依赖：在requirements.txt中添加所需依赖
3. 编写测试：在main_test.py中添加单元测试
4. 配置Dockerfile：根据需要调整Dockerfile
5. 创建Cloud Build配置：修改cloudbuild.yaml文件

解析器测试与部署

完成解析器开发后，可以通过以下命令运行测试：

pytest bq-workers/your-source-parser/main_test.py

测试通过后，即可通过Cloud Build部署解析器：

gcloud builds submit --config bq-workers/your-source-parser/cloudbuild.yaml .

代码提交与审核

提交Pull Request

1. 创建新的分支进行开发：

git checkout -b feature/your-feature-name

2. 提交代码并推送到远程仓库：

git add . git commit -m "Add your commit message here" git push origin feature/your-feature-name

3. 在GitHub上创建Pull Request，等待项目维护者审核

参与社区讨论

• 加入#fourkeys Slack频道参与讨论
• 参加定期的线上Office Hours
• 关注项目ROADMAP.md了解未来发展计划

查看贡献成果

成功贡献代码后，你可以在Grafana仪表盘中看到新解析器带来的数据：

仪表盘展示了四大关键指标的实时数据，包括变更前置时间、部署频率、变更失败率和服务恢复时间等。

总结

通过本指南，你已经了解了如何为Four Keys项目贡献代码和扩展自定义解析器。无论是修复bug、添加新功能还是开发自定义解析器，你的每一个贡献都将帮助项目变得更加强大。开始你的开源贡献之旅吧！

【免费下载链接】fourkeysPlatform for monitoring the four key software delivery metrics of software delivery项目地址: https://gitcode.com/gh_mirrors/fo/fourkeys