diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD new file mode 100644 index 0000000..b169398 --- /dev/null +++ b/CONTRIBUTING.MD @@ -0,0 +1,140 @@ +# 对 BackDoorBuster 的贡献指南 + +我们欢迎大家对我们的项目作出贡献!本文档提供了贡献指南,以确保每位贡献者都能顺利进行合作。 + +## 开始之前 + +在开始之前,请确保: +- 安装好 `python` 环境 +- 熟悉使用 `git` 进行版本控制([Git 文档](https://git-scm.com/doc))。 + +## 如何贡献 + +### 报告问题 + +在创建问题报告之前,请先检查已有的问题列表,看看是否已经有人报告了相同的问题。创建问题报告时,请尽可能包括更多细节: +- 使用清晰和描述性的标题。 +- 描述复现问题的确切步骤,包括尽可能多的细节。 +- 提供具体例子来展示这些步骤。 +- 描述你在执行步骤后观察到的行为,并指出这种行为的具体问题所在。 +- 解释你期望看到的行为及其原因。 + +如果您有一个新的功能想法或对现有功能的改进建议,欢迎在 GitHub 仓库的 Issues 部分提出。在提出需求时,请确保: + +- 使用清晰和具体的标题来描述需求。 +- 在描述中详细说明需求的背景、目标以及预期的效果。 +- 提供实现该功能可能涉及的详细步骤或考虑的技术点。 +- 标记相关的项目维护者或团队,以便他们能够注意到这个需求。 + +#### 如何提出有效的需求: + +1. 确认之前没有人提出过相同的需求。 +2. 提供足够的信息以便他人理解这一需求的价值和用途。 +3. 可选地,提供一个可能的实现方案或示例,帮助他人更好地理解需求。 + +### 响应需求 + +如果您想参与实现某个已提出的需求: + +1. 在该需求的 Issue 下留言,表明您想要参与实现,以及您打算如何着手。 +2. 讨论并获得社区或项目维护者的反馈。 +3. 一旦您准备好开始工作,可以新建一个功能分支,分支名建议格式为 `feature/功能名称`。 + +#### 创建和使用功能分支: + +1. 从最新的主分支创建您的功能分支: + ```bash + git checkout -b feature/your-feature-name main + ``` + +### 贡献代码 + +#### 设置开发环境 + +1. 在页面顶部找到并 Fork 仓库。 +2. 将 Fork 过去的仓库克隆到本地机器: + ```bash + https://git.mamahaha.work/sangge/BackDoorBuster.git + ``` +3. 设置开发环境。确保已安装 Python,并根据项目需求选择是否安装 Docker。 + +#### 进行更改 + +1. 创建一个新分支: + ```bash + git checkout -b feature/你的新功能名 + ``` +2. 进行更改,编写清晰、可读和模块化的代码。 +3. 使用 `black` 进行代码格式化: + ```bash + black your_module.py + ``` +4. 确保你的更改符合编码标准(PEP8),并为新代码或更改添加单元测试。 +5. 提交你的更改: + ```bash + git add . + git commit -m "添加描述性的提交信息" + ``` +6. 将分支推送到 GitHub: + ```bash + git push origin feature/你的新功能名 + ``` + +### 提交拉取请求 + +1. 导航到本仓库。 +2. 点击“New pull request”按钮。 +3. 选择你的分支以及要对比的项目主分支。 +4. 提供你更改的详细描述及其原因。 +5. 提交拉取请求。 + +## 工作流与拉取请求处理 + +为了保证项目的代码质量和稳定性,我们实施了严格的审核流程。每个拉取请求(PR)必须满足以下要求才能被合并到主分支: + +### 成员审核 + +- **审批要求**:每个拉取请求必须至少获得两位团队成员的审批。 +- **审批流程**: + - 审批者需要仔细检查 PR 的代码质量、结构和符合项目目标的程度。 + - 审批者应该在评论中提供反馈,如果需要更改,应明确指出。 + - 审批者可以使用平台的审批功能来正式批准或请求更改。 + +### 状态检查 + +- **状态检查要求**:所有 PR 必须通过配置的状态检查,这通常包括自动化测试、代码风格检查等。 +- **配置状态检查**: + - 必须通过所有指定的自动化测试。 + - 必须满足代码格式化标准,例如使用 `black` 格式化 Python 代码。 +- **检查完成**:只有当所有状态检查都显示为“通过”(green status),PR 才能被合并。 + +### 合并标准 + +- 在合并前,除了必须获得必要的审批和通过所有状态检查外,还应确保 PR 没有与主分支的冲突。 +- PR 应基于最新的主分支进行合并,以避免合并冲突和其他潜在问题。 + +## 代码风格和约定 + +- 遵循 PEP8 描述的标准命名约定。 +- 使用 docstrings 和必要时的注释来文档化你的代码。 +- 确保使用类型提示,遵循 PEP 484 描述的规范。 +- 保持函数专注且紧凑;避免可能的大型单体函数。 + +## 使用工具 + +- **格式化**:我们使用 `black` 自动格式化代码。 + - 使用 pip 安装 black: + ```bash + pip install black + ``` + - 运行 black 确保你的代码符合我们的编码标准: + ```bash + black path/to/your_code.py + ``` + +## 测试 + +- 使用 `unittest` 编写你的代码测试。 +- 确保所有测试在提交拉取请求之前都能通过。 + +感谢您为 BackDoorBuster 做出的贡献!我们非常感谢您的努力,使这个项目变得更好。