这是本节的多页打印视图。 点击此处打印.

返回本页常规视图.

参与贡献

如何参与贡献

感谢您对Capa的支持！

1 - 贡献者指南

为任何Capa项目资源库做出贡献的通用指南

Capa 基于 Apache 2.0 许可发布，遵循标准的 Github 开发流程。 本文档描述了如何使用 Github Issue 和 Pull Request 对Capa做出贡献。

Issues 约定

  1. Question: 提出一个关于 Capa 的问题
  2. Feature Request: 提出一个关于 Capa 新功能的请求
  3. Bug Report: 提出一个 Bug 的报告
  4. Discussion: 对 Capa 的讨论
  5. Proposal: 对 Capa 的提案

编码规范约定

  1. 提交的代码一律要添加 Apache License（可以通过checkstyle插件来检测）
  2. 每次只允许提交一个 Commit，如果有多个在本地 Rebase 成一个 Commit
  3. 建议一个 Commit 只解决一个 Issue
  4. Commit 中要有详细的说明，且一律使用英文来描述
  5. CI Pipeline 构建失败的代码不会进入 Code Review 环节
  6. 代码仓库有且仅有一个主干分支（master分支）
  7. 主干分支上的代码只能通过 Merge PR（MR）向前推进
  8. 所有实现的 Feature 都要有完善使用说明文档
  9. 仅在 UT 中引用到的 Package 的 Scope 必须是 test
  10. 每个问题都要先提交一个Issue

单测规范约定

  1. 单元测试统一用 junit 和 mockito
  2. 遵守AIR原则
    • Automatic（自动化）。单元测试应该是全自动执行的，并且非交互式的。测试用例通常是被定期执行的，执行过程必须完全自动化。
    • Independent（独立性）。保持单元测试的独立性。为了保证单元测试稳定可靠且便于维护，单元测试用例之间决不能互相调用，也不能依赖执行的先后次序。
    • Repeatable（可重复）。单元测试是可以重复执行的，不能受到外界环境的影响。
  3. 保持单元测试用例的运行速度，不要将大的集成用例放在单元测试中
  4. UT类命名规范 BeTestedClassTest
   范例：
   源类的全限定名为 com.api.Matching
   源文件路径 src/main/java/com/api/Matching.java
   UT文件路径 src/test/java/com/api/MatchingTest.java
  1. UT方法命名规范
   范例：
   源方法名为 matching()
   UT方法命名为 testMatching_Success()/testMatching_SuccessWhenResultGreaterThanZero()/testMatching_FailWhenThrowException()

Commit 约定

  1. Commit style
 <type>(<scope>): <subject>
 <BLANK LINE>
 <body>
 <BLANK LINE>
 <footer>
  1. Commit type
    • feat: 新增 feature
    • fix：修复 bug
    • docs：仅仅修改了文档，比如 README, CHANGELOG, CONTRIBUTE等等
    • style：仅仅修改了空格、格式缩进、逗号等等，不改变代码逻辑
    • refactor：代码重构，没有加新功能或者修复 bug
    • perf：优化相关，比如提升性能、体验
    • test：测试用例，包括单元测试、集成测试等
    • chore：改变构建流程、或者增加依赖库、工具等
    • revert：回滚到上一个版本
  2. Commit scope: 提交代码适用的范围（选填）
  3. Commit subject：50个字符以内，描述主要变更内容（必填）
  4. Commit body：更详细的说明文本，建议72个字符以内（必填）
  5. Commit footer：如果需要的化可以添加一个链接到issue地址或者其它文档，或者关闭某个issue（选填）

2 - 文档贡献指南

为Capa文档贡献的指南

本文档描述了如何为 Capa 文档库做出贡献。文档库使用 Markdown 语法编写。已发布到 capa-cloud/capa.io。

先决条件

Capa 文档库使用 Hugo 的 Docsy 主题构建。

文档搭建步骤

文档开发步骤

规范约定

  1. 确保你所贡献文件在层次结构中的位置是正确的。
  2. 确保你所贡献内容在名称、参数、术语方面保持一致。
  3. 确保任何贡献内容在 Web 站点可以构建成功。
  4. 确保读者能够理解为什么他们应该关注贡献内容，以及能够为他们解决什么问题。

文档路径说明

文件路径说明

文件统一放在 content/ 目录下，其中中文文档存放于 content/zh ，英文文档存放于 content/en。

如果需要新增文档，需要按照目录结构新增文件夹和.md文件。

图片路径说明

图片统一放在 content/images/ 目录下，其中图片目录结构与所引用的 md 文件的目录保持一致。需要选用清晰且与背景适配的图片。

文档中统一使用全路径来引用图片，Url前缀 https://raw.githubusercontent.com/capa-cloud/capa.io/master/content/images 。

例如，引入下图的图片（contribution_file.png），Markdown写法如下：

 ![Architecture](https://raw.githubusercontent.com/capa-cloud/capa.io/master/content/images/zh/docs/ContributionGuidelines/contribution_file.png)
  • master 表示分支名
  • content/images/zh/docs/ContributionGuidelines/contribution_file.png 表示图片的相对路径