From 0b0d083109e13a3c81363ee0f07305240ebe12db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=99=BE=E5=B0=8F=E5=83=A7?= Date: Sat, 23 Mar 2024 12:37:46 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=98=8A=20=E9=81=B5=E5=BE=AA=E5=9B=BD?= =?UTF-8?q?=E9=99=85=E5=BC=80=E6=BA=90=E8=A7=84=E8=8C=83=EF=BC=8C=E8=A1=A5?= =?UTF-8?q?=E5=85=85=E5=BC=80=E6=BA=90=E4=BB=93=E5=BA=93=E8=AF=B4=E6=98=8E?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- BRANCH_MANAGEMENT.md | 41 ++++++++++++++++++ CONTRIBUTING.md | 101 +++++++++++++------------------------------ DEVELOPMENT_SETUP.md | 51 ++++++++++++++++++++++ TESTING_GUIDE.md | 48 ++++++++++++++++++++ references/index.md | 2 +- 源码目录说明.md | 8 +++- 6 files changed, 178 insertions(+), 73 deletions(-) create mode 100644 BRANCH_MANAGEMENT.md create mode 100644 DEVELOPMENT_SETUP.md create mode 100644 TESTING_GUIDE.md diff --git a/BRANCH_MANAGEMENT.md b/BRANCH_MANAGEMENT.md new file mode 100644 index 0000000000..ffaef997d8 --- /dev/null +++ b/BRANCH_MANAGEMENT.md @@ -0,0 +1,41 @@ +# 分支管理文档 + +## 1. 工作流概述 + +`Furion` 项目采用了 [GitFlow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) 工作流进行分支管理，这是一种专门为大型项目设计的长期支持性分支模型。其核心理念是分离出主干分支（`main` 或 `master`）、开发分支 (`develop`)、特性分支 (`feature/*`)、发布分支 (`release/*`) 和热修复分支 (`hotfix/*`)。 + +## 2. 主要分支类型 + +### 2.1 主干分支（Main Branch） + +- `main`: 代表生产环境下的稳定版本。只有在发布新版本时才从发布分支合并到主干分支。 + +### 2.2 开发分支（Develop Branch） + +- `develop`: 是日常开发的主要分支，包含所有即将发布的功能。所有特性分支完成后均应合并至开发分支。 + +### 2.3 特性分支（Feature Branches） + +- `feature/*`: 当开发新的功能或改进时，应从开发分支 (`develop`) 上创建特性分支。完成后，通过 Pull Request 合并回 `develop` 分支。 + +### 2.4 发布分支（Release Branches） + +- `release/*`: 当准备发布新版本时，从 `develop` 分支创建发布分支，用于做最终的测试和文档修订。确认无误后，合并到 `main` 和 `develop` 分支。 + +### 2.5 热修复分支（Hotfix Branches） + +- `hotfix/*`: 如果生产环境中发现严重问题，需要立即修复，则从 `main` 分支创建热修复分支。修复完成后，同时合并回 `main` 和 `develop` 分支。 + +## 3. 分支操作指南 + +1. **新建特性分支**: `git checkout -b feature/your-feature develop` +2. **完成开发**: 完成开发后，确保本地代码通过所有测试，并将特性分支推送到远程仓库。 +3. **发起 Pull Request**: 在 GitHub/Gitee 等平台上对比 `develop` 分支发起 Pull Request，并等待至少一名维护者的审核和合并。 +4. **合并分支**: 经过评审和必要的讨论后，由维护者将特性分支合并到 `develop` 分支。 + +## 4. 注意事项 + +- 请确保在每个提交中附带清晰、简洁的提交消息，遵循项目的提交消息规范。 +- 在合并前确保分支是最新的，避免出现合并冲突。 + +感谢您的配合，遵循上述分支管理策略将使 `Furion` 项目的开发更加有序、高效！ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 73ef766151..6c293d3e35 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,95 +1,56 @@ -# 反馈/贡献 +# 贡献指南 -![输入图片说明](https://gitee.com/dotnetchina/Furion/raw/v4/handbook/static/img/tip.png) +感谢您对 `Furion` 项目的关注和贡献！本指南将指导您如何有效参与到项目中来，共同构建更强大的开源框架。 -## 💢 特别说明：如果 Issue 没有严格按照模板编写且未提供测试源码下载或 Git 测试仓库地址，则视为无效 `Issue`，将无法得到答复。 +## 错误报告 -### Furion 版本号 +若您在 `Furion` 中发现了非安全相关的漏洞，请首先在 `Furion` 仓库的 [Issues](https://gitee.com/dotnetchina/Furion/issues) 中搜索以确认该问题尚未被提交。若未找到相似问题，请创建一个新的 Issue，并详尽描述漏洞详情、重现步骤及环境信息。 -哪个版本号？（升级至最新版后还有问题再反馈） +## 安全问题处理 ---- - -### .NET SDK 版本号 +对于安全问题的披露，请遵循以下流程： -- [ ] .NET5 -- [ ] .NET6 -- [ ] .NET7 +1. **收集信息**：尽可能详细地记录漏洞的描述、影响范围、可能的攻击方法等信息。您可以在报告中提供相关的截图、日志文件等辅助信息。 +2. **联系方式**：请您提供您的联系方式，以便我们与您进行进一步的沟通和反馈。您可以在报告中留下您的电子邮件地址、社交媒体账号或其他可靠的联系方式。 +3. **发送报告**：请将您的安全漏洞报告发送至我们指定的安全邮箱 (monksoul@outlook.com) 或报告渠道（作者微信：ibaiqian）。如果我们有提供特定的报告指南或漏洞报告表格，请您按照指示进行报告。如果没有特定的指引，您可以通过邮件发送报告给我们的安全团队。 +4. **等待回复**：我们将尽快收到您的报告后进行评估，并在确认漏洞的准确性后与您联系。请理解我们可能需要一些时间来进行调查和修复漏洞，我们会及时地与您保持沟通并提供进展更新。 ---- +## 解决现有问题 -### 项目类型 +欢迎您浏览仓库的 [Issues](https://gitee.com/dotnetchina/Furion/issues) 列表，挑选并尝试解决其中的问题。一旦解决问题，请提交 Pull Request，并在描述中关联到原始的 Issue 编号。 -- [ ] WebApi -- [ ] Mvc -- [ ] Razor Pages -- [ ] Blazor Server -- [ ] MinApp -- [ ] WinForm -- [ ] WPF -- [ ] Console +## 提出新功能建议 ---- +我们鼓励通过 [Issues](https://gitee.com/dotnetchina/Furion/issues) 来提议新功能，并使用 "Feature/新特性" 标签标记。另外，也可以通过邮件（请参阅项目文档获取联系方式）向我们发送您的建议。项目团队会在评估后，将确认开发的新功能纳入下一个版本的计划任务列表。 -### 操作系统和版本 +## 开发环境搭建与测试运行 -- [ ] Windows（版本号？） -- [ ] Linux（版本号？） -- [ ] MacOS（版本号？） -- [ ] 其他（版本号？） +从 `git clone https://gitee.com/dotnetchina/Furion.git` 开始，参照我们的 [开发环境配置文档](./DEVELOPMENT_SETUP.md) 设置 IDE 和其他相关环境。运行测试时，请按照 [测试指南](./TESTING_GUIDE.md) 操作。 ---- +## 变更日志撰写规则 -### 代码环境 +1. 使用现在时态描述变更。 +2. 首行简洁扼要，字数适中。 +3. 描述变更内容需准确、完整，符合项目的变更日志规范。 -- [ ] 开发环境（Development） -- [ ] 生产环境（Production） -- [ ] 测试环境（Tests/单元测试/集成测试 ） +## 编码约定 ---- +遵循项目内的编码约定，具体见 [`.editorconfig`](https://gitee.com/dotnetchina/Furion/blob/v4/framework/.editorconfig) 文件。 -### 描述你的问题 +## 分支管理约定 -发生了什么？ +我们采用 [GitFlow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) 分支管理模式进行开发，详细规定见 [分支管理文档](./BRANCH_MANAGEMENT.md)。 ---- - -### 异常堆栈信息 - -异常堆栈是什么？ - ---- +## 合并 Pull Request 的流程 -### 测试项目代码 +当满足以下条件时，您的 Pull Request 可以被合并至 `master/main` 分支： -> **⚠⚠ 必须提供完整可运行且包含错误的 `Git` 仓库 DEMO，DEMO 提供最简单的错误逻辑代码，否则将无法得到答复。⚠⚠** +1. 通过持续集成 (CI) 测试。 +2. 至少获得两位维护者的批准。 +3. 确保与最新版本兼容且无冲突。 -您的代码下载地址？ +**重要提示**：无论您是修复了 bug 还是改进了功能，我们都强烈建议您将更改同步回上游（即 `Furion` 主仓库）。请在完成工作后通过 Pull Request 或邮件通知我们，我们将迅速进行审核并考虑合并您的改动。 --- -### 数据库信息和版本 - -请提供安装的 `NuGet` 包版本号。 - -- [ ] Sqlite（包名和版本号？） -- [ ] SqlServer（包名和版本号？） -- [ ] MySQL（包名和版本号？） -- [ ] Oracle（包名和版本号？） -- [ ] PostgreSQL（包名和版本号？） -- [ ] Firebird（包名和版本号？） -- [ ] Cosmos（包名和版本号？） -- [ ] InMemoryDatabase（包名和版本号？） -- [ ] 无 - ---- - -### 期待结果 - -期待的结果是？ - ---- - -### 确认工单 - -**为了减少不必要的沟通成本和时间成本，请再次确认 `Issue` 已按照要求正确填写，否则将被直接关闭。** \ No newline at end of file +请尊重并遵守我们的 [行为准则](./CODE_OF_CONDUCT.md)，让我们共同营造一个友善、合作的开源社区氛围。感谢您的每一次贡献，若有任何疑问或需要协助，请随时联系我们。 diff --git a/DEVELOPMENT_SETUP.md b/DEVELOPMENT_SETUP.md new file mode 100644 index 0000000000..476f0420c7 --- /dev/null +++ b/DEVELOPMENT_SETUP.md @@ -0,0 +1,51 @@ +# 开发环境配置文档 + +## 1. 安装 Visual Studio 2022 Preview Enterprise + +### 1.1 下载安装 + +访问 [Visual Studio 官方网站](https://visualstudio.microsoft.com/zh-hans/vs/preview/) 下载 Visual Studio 2022 Preview Enterprise 版本。确保选择适合您操作系统的版本，并确保系统满足最低硬件和软件要求。 + +### 1.2 安装过程 + +1. 运行安装程序，选择“自定义”安装选项。 +2. 在工作负载选择界面，确保勾选“ASP.NET 和 Web 开发” workload，这将自动包含 .NET 框架的多个版本支持。 +3. 在单个组件部分，滚动查找并勾选您需要的 .NET SDK 版本，包括但不限于： + - .NET 5.x SDK + - .NET 6.x SDK + - .NET 7.x SDK + - .NET 8.x SDK + - .NET 9.x SDK +4. 确认所有所需组件已勾选后，开始安装过程。 + +### 1.3 验证安装 + +安装完成后，打开 Visual Studio 2022 并通过“工具” > “获取工具和功能…”检查已安装的组件，确认 .NET SDK 是否正确安装。 + +## 2. 安装 CodeMaid 2022 + +[CodeMaid](https://www.codemaid.net) 是一个优秀的 Visual Studio 扩展，用于提高代码质量和可读性，提供代码清理、格式化等功能。 + +### 2.1 安装扩展 + +1. 在 Visual Studio 中，转到“扩展” > “管理扩展”（或快捷键 Ctrl + Shift + X）。 +2. 在在线市场搜索栏中输入“CodeMaid”。 +3. 找到 CodeMaid 并点击“下载”按钮安装。 +4. 安装完成后，重启 Visual Studio 以激活 CodeMaid。 + +### 2.2 配置 CodeMaid + +1. 安装完毕后，可在“工具” > “选项” > “CodeMaid”中配置 CodeMaid 的默认设置。 +2. 根据个人喜好和团队规范调整 CodeMaid 的清理规则和代码样式。 + +## 3. 配置项目 + +对于新的或现有的 C#/ASP.NET Core 项目，确保在项目属性中设置了正确的 .NET SDK 版本目标框架。 + +至此，您的开发环境已经准备好支持 C#/ASP.NET Core 开发，并配备了 CodeMaid 代码清理工具，您可以开始愉快地进行项目开发了。 + +--- + +注意：由于 .NET SDK 更新频繁，请定期检查并更新至最新版本以获得最佳体验和安全性保障。 + +--- diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md new file mode 100644 index 0000000000..c4b0f72932 --- /dev/null +++ b/TESTING_GUIDE.md @@ -0,0 +1,48 @@ +# 测试指南 + +## 1. 安装测试依赖 + +### 1.1 xUnit 安装 + +在单元测试项目中，使用 NuGet 安装 [xUnit](https://xunit.net/) 测试框架及相关组件： + +```shell +dotnet new xunit -n Furion.UnitTests +cd Furion.UnitTests + +dotnet add package xunit +dotnet add package xunit.runner.visualstudio +dotnet add package coverlet.msbuild + +dotnet add package Furion.Xunit; +``` + +### 1.2 ASP.NET Core MVC 测试支持 + +为了进行针对 Controllers 和 Services 的集成测试，安装 `Microsoft.AspNetCore.Mvc.Testing` 包： + +```shell +dotnet add package Microsoft.AspNetCore.Mvc.Testing +``` + +## 2. 编写和执行单元测试 + +### 2.1 xUnit 单元测试 + +在测试项目中创建测试类，并使用 `[Fact]` 特性标记单元测试方法。xUnit 提供了丰富的断言方法用于验证预期结果。 + +### 2.2 ASP.NET Core MVC 集成测试 + +对于涉及到 ASP.NET Core MVC 控制器的测试，可以利用 `WebApplicationFactory` 创建一个模拟的 HTTP 客户端环境来进行集成测试。 + +例如，创建一个测试类继承自 `WebApplicationFactory`，然后在测试方法中使用模拟的 HTTP 客户端请求并验证响应结果。 + +## 3. 参考资料 + +有关如何使用 xUnit 编写具体的单元测试，请参考 Furion 官方文档中的单元测试章节：[https://furion.net/docs/unittest](https://furion.net/docs/unittest) + +文档中涵盖了如何组织测试项目结构，如何编写针对服务和控制器的单元测试，以及如何利用 xUnit 的各种特性进行复杂的测试场景。 + +--- + +请注意，在实际项目中，您需要根据 Furion 项目的实际情况填充测试类的具体内容。上述指南只是提供了安装测试依赖和大致的测试框架使用方向，详细的实际测试代码请参考链接中的官方文档。 diff --git a/references/index.md b/references/index.md index f92086ee3a..aa73fe0f26 100644 --- a/references/index.md +++ b/references/index.md @@ -1,4 +1,4 @@ -**中** | [En](https://github.com/MonkSoul/Furion) | 允许商用，慷慨[赞助](https://furion.net/docs/donate) +**中** | [En](https://github.com/MonkSoul/Furion) # 先知 diff --git a/源码目录说明.md b/源码目录说明.md index da6532643f..429aee34e7 100644 --- a/源码目录说明.md +++ b/源码目录说明.md @@ -7,18 +7,22 @@ `├──` **`framework`** — `Furion` 框架代码
`├──` **`references`** — `Furion` API 文档源码
`├──` **`samples`** — `Furion` 框架演示例子
-`├──` **`schema`** — `Furion` 配置文件 `JSON Schema`
+`├──` **`schemas`** — `Furion` 配置文件 `JSON Schema`
`├──` **`snks`** — `Furion` 强签名密钥目录
`├──` **`templates`** — `Furion` 脚手架源码
`├──` **`tests`** — `Furion` 单元测试源码
`├──` **`tools`** — `Furion.Tools` 命令行工具开发源码
`├──` **`.gitattributes`** — `Github` 和 `Gitee` 仓库配置
`├──` **`.gitignore`** — `Github` 和 `Gitee` 仓库忽略目录/文件配置
+`├──` **`BRANCH_MANAGEMENT.md`** — 分支管理文档
`├──` **`CHANGELOG.md`** — `Furion` 更新日志
-`├──` **`CONTRIBUTING.md`** — `Furion` 贡献/Issue 指南
+`├──` **`CODE_OF_CONDUCT.md`** — 行为准则
+`├──` **`CONTRIBUTING.md`** — 贡献指南
+`├──` **`DEVELOPMENT_SETUP.md`** — 开发环境配置文档
`├──` **`Dockerfile`** — `Furion` 演示例子 `samples` 的 `Docker` 构建文件
`├──` **`LICENSE`** — `Furion` 仓库开源协议
`├──` **`LICENSE.zh`** — `Furion` 仓库开源协议中文版
`├──` **`README.md`** — `Furion` 国际版仓库介绍
`├──` **`README.zh.md`** — `Furion` 中国版仓库介绍
`├──` **`nuget-push.ps1`** — 自动发布到 `NuGet` 平台脚本
+`├──` **`TESTING_GUIDE.md`** — 测试指南