OVH The Bastion 项目代码贡献规范与技术指南

OVH The Bastion 项目代码贡献规范与技术指南

项目概述

OVH The Bastion 是一个安全堡垒机解决方案，为服务器访问提供安全审计和访问控制功能。作为开源项目，它遵循严格的代码质量和贡献规范，确保系统的安全性和稳定性。

代码贡献基本原则

在参与该项目开发前，开发者需要了解以下核心原则：

1. 设计一致性：所有代码必须遵循项目架构设计文档中的设计决策
2. 代码质量：严格遵守编码风格规范
3. 测试覆盖：新增功能必须包含相应的单元测试或集成测试
4. 文档完整：代码变更需附带相应文档说明
5. 法律合规：所有贡献必须签署开发者原创证书(DCO)

编码规范详解

通用规范

• 使用4个空格缩进，禁止使用制表符(Tab)
• 所有源文件包含Vim模式行(modelines)，方便Vim用户自动适配

Perl语言规范

1. 代码格式化：

   • 必须使用项目提供的perl-tidy.sh脚本进行代码格式化
   • 必须通过perl-critic.sh脚本检查，无任何警告

2. 模块依赖：

   • 优先使用Perl核心模块
   • 如需使用非核心模块，必须满足：
     • 在Debian所有支持版本中已打包
     • 在其他支持操作系统上可通过可信第三方仓库获取
     • 禁止使用cpan install直接安装

Shell脚本规范

• Bash和POSIX shell脚本必须通过shell-check.sh检查
• 无任何shellcheck警告

代码提交流程

1. 修改提交：

   • 通过Pull Request方式提交变更
   • 每个PR应专注于单一功能或问题修复

2. 测试验证：

   • 确保新增代码通过所有现有测试
   • 为新功能添加适当的测试用例

3. 文档更新：

   • 更新相关文档说明变更
   • 添加必要的代码注释

许可证要求

项目采用Apache License 2.0许可证，所有贡献必须遵循：

1. 新文件必须包含明确的版权声明
2. 所有贡献代码必须采用相同许可证
3. 禁止引入采用不兼容许可证的代码

开发者原创证书(DCO)详解

DCO是确保代码来源合法性的重要机制，贡献者需确认：

1. 原创性声明：

   • 确认贡献代码为原创或有权以开源形式提交
   • 确认代码不侵犯第三方知识产权

2. 签名要求：

   • 使用真实姓名签署(Signed-off-by)
   • 匿名或化名贡献不被接受

3. 法律效力：

   • 签名表示接受贡献将被公开记录
   • 确认理解项目许可证条款

签名格式示例：

Signed-off-by: 张三 <zhangsan@example.com>

最佳实践建议

1. 开发环境配置：

   • 配置编辑器使用4空格缩进
   • 安装shellcheck、perltidy等工具

2. 代码审查：

   • 提交前自行运行所有检查脚本
   • 确保代码风格与项目现有代码一致

3. 测试策略：

   • 新功能应包含单元测试
   • 关键路径需增加集成测试
   • 边界条件需特别测试

通过遵循这些规范，开发者可以确保贡献被顺利接受，同时维护项目的高质量标准和安全要求。