diff --git a/.github/ISSUE_TEMPLATE/01-bug-report.yml b/.github/ISSUE_TEMPLATE/01-bug-report.yml new file mode 100644 index 00000000..cf1156ad --- /dev/null +++ b/.github/ISSUE_TEMPLATE/01-bug-report.yml @@ -0,0 +1,110 @@ +name: "Bug Report / 缺陷报告" +description: "Report a reproducible defect in GFramework. / 报告可稳定复现的 GFramework 缺陷。" +title: "[Bug]: " +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to report a bug. + + 感谢你提交缺陷报告。提交前请先搜索已有 Issue，并尽量提供最小复现信息。 + - type: checkboxes + id: checks + attributes: + label: "Pre-Submission Checks / 提交前检查" + description: "Please confirm the following items before submitting. / 提交前请确认以下事项。" + options: + - label: "I searched existing issues and did not find a duplicate. / 我已搜索现有 Issue，未发现重复问题。" + required: true + - label: "I checked the relevant README or docs pages first. / 我已先阅读相关 README 或文档。" + required: true + - label: "I can describe a reproducible scenario or provide a minimal repro. / 我可以描述稳定复现场景或提供最小复现。" + required: true + - type: dropdown + id: module + attributes: + label: "Affected Module / 影响模块" + description: "Choose the module that best matches the problem. / 请选择最符合问题范围的模块。" + options: + - "GFramework.Core" + - "GFramework.Core.Abstractions" + - "GFramework.Game" + - "GFramework.Game.Abstractions" + - "GFramework.Godot" + - "GFramework.SourceGenerators" + - "GFramework.Godot.SourceGenerators" + - "Docs / 文档" + - "Build / CI / Packaging" + - "Unknown / Not sure / 不确定" + validations: + required: true + - type: input + id: version + attributes: + label: "Package or Commit Version / 包版本或提交版本" + description: "Example: NuGet version, commit SHA, or branch. / 例如 NuGet 版本、提交 SHA 或分支。" + placeholder: "e.g. GeWuYou.GFramework.Core 1.2.3 / main@abc1234" + validations: + required: true + - type: textarea + id: summary + attributes: + label: "Bug Summary / 问题概述" + description: "Describe the defect in one or two paragraphs. / 用 1-2 段简要描述问题。" + placeholder: "What is broken, and when does it happen? / 具体哪里出错，什么情况下出现？" + validations: + required: true + - type: textarea + id: steps + attributes: + label: "Steps To Reproduce / 复现步骤" + description: "Provide a deterministic repro whenever possible. / 尽量提供可稳定复现的步骤。" + placeholder: | + 1. ... + 2. ... + 3. ... + validations: + required: true + - type: textarea + id: expected + attributes: + label: "Expected Behavior / 预期行为" + description: "What should happen instead? / 正常情况下应该发生什么？" + validations: + required: true + - type: textarea + id: actual + attributes: + label: "Actual Behavior / 实际行为" + description: "What actually happens? Include exception text if available. / 实际发生了什么？如有异常请附上。" + validations: + required: true + - type: textarea + id: repro + attributes: + label: "Minimal Repro / 最小复现" + description: "Share a repository, gist, code snippet, or explain why a minimal repro is not yet available. / 提供仓库、gist、代码片段，或说明暂时无法提供的原因。" + render: shell + - type: textarea + id: logs + attributes: + label: "Logs and Screenshots / 日志与截图" + description: "Paste relevant logs, stack traces, or attach screenshots. / 粘贴相关日志、堆栈，或补充截图。" + render: shell + - type: textarea + id: environment + attributes: + label: "Environment / 环境信息" + description: "List the environment details that matter for reproduction. / 请列出与复现相关的环境信息。" + placeholder: | + - OS: + - .NET SDK / Runtime: + - Godot version (if applicable): + - IDE / Build tool: + validations: + required: true + - type: textarea + id: impact + attributes: + label: "Impact and Scope / 影响范围" + description: "Explain whether this blocks adoption, breaks compatibility, or affects only a narrow scenario. / 说明该问题是否阻塞使用、破坏兼容性，还是仅影响较窄场景。" diff --git a/.github/ISSUE_TEMPLATE/02-feature-request.yml b/.github/ISSUE_TEMPLATE/02-feature-request.yml new file mode 100644 index 00000000..37614b6b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/02-feature-request.yml @@ -0,0 +1,80 @@ +name: "Feature Request / 功能建议" +description: "Suggest a new capability or an API improvement. / 提出新能力或 API 改进建议。" +title: "[Feature]: " +body: + - type: markdown + attributes: + value: | + Use this form for feature proposals, API improvements, and workflow enhancements. + + 该模板适用于新功能、API 改进和工作流优化建议。请优先描述问题和动机，而不只是直接给出实现方案。 + - type: checkboxes + id: checks + attributes: + label: "Pre-Submission Checks / 提交前检查" + description: "Please confirm the following items before submitting. / 提交前请确认以下事项。" + options: + - label: "I searched existing issues and did not find the same request. / 我已搜索现有 Issue，未发现相同建议。" + required: true + - label: "I checked the relevant docs, examples, or current APIs first. / 我已先检查相关文档、示例或现有 API。" + required: true + - label: "I can explain the user problem or workflow gap this request solves. / 我可以说明该建议要解决的用户问题或工作流缺口。" + required: true + - type: dropdown + id: module + attributes: + label: "Target Module / 目标模块" + description: "Choose the module that should own this capability. / 请选择最适合承载该能力的模块。" + options: + - "GFramework.Core" + - "GFramework.Core.Abstractions" + - "GFramework.Game" + - "GFramework.Game.Abstractions" + - "GFramework.Godot" + - "GFramework.SourceGenerators" + - "GFramework.Godot.SourceGenerators" + - "Docs / 文档" + - "Build / CI / Packaging" + - "Cross-cutting / 跨模块" + - "Unknown / Not sure / 不确定" + validations: + required: true + - type: textarea + id: problem + attributes: + label: "Problem Statement / 问题背景" + description: "What problem are you facing today? / 你当前遇到的核心问题是什么？" + placeholder: "Describe the workflow pain, limitation, or missing capability. / 描述当前流程痛点、限制或缺失能力。" + validations: + required: true + - type: textarea + id: proposal + attributes: + label: "Proposed Solution / 建议方案" + description: "Describe the behavior, API shape, or user experience you want. / 描述你期望的行为、API 形态或使用体验。" + placeholder: "What should GFramework provide? / 希望 GFramework 提供什么？" + validations: + required: true + - type: textarea + id: use-cases + attributes: + label: "Use Cases / 使用场景" + description: "Show the practical scenarios this would unlock or simplify. / 说明该能力能解决或简化哪些实际场景。" + validations: + required: true + - type: textarea + id: api-sketch + attributes: + label: "API or Design Sketch / API 或设计草图" + description: "Optional but helpful: provide pseudocode, API examples, or a rough design. / 可选但强烈建议：补充伪代码、API 示例或设计草图。" + render: csharp + - type: textarea + id: alternatives + attributes: + label: "Alternatives Considered / 已考虑的替代方案" + description: "Describe current workarounds or alternatives and why they are insufficient. / 描述现有替代方案或绕过方式，以及为什么不足。" + - type: textarea + id: compatibility + attributes: + label: "Compatibility and Migration Impact / 兼容性与迁移影响" + description: "State whether this needs breaking changes, opt-in behavior, or migration notes. / 说明该建议是否涉及破坏性变更、显式开关或迁移说明。" diff --git a/.github/ISSUE_TEMPLATE/03-documentation.yml b/.github/ISSUE_TEMPLATE/03-documentation.yml new file mode 100644 index 00000000..2720a727 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/03-documentation.yml @@ -0,0 +1,61 @@ +name: "Documentation / 文档改进" +description: "Report missing, outdated, or unclear documentation. / 报告缺失、过期或不清晰的文档。" +title: "[Docs]: " +body: + - type: markdown + attributes: + value: | + Documentation issues are product issues in this repository. + + 文档问题同样是产品问题。请尽量指出具体页面、段落和建议修正方向，方便快速处理。 + - type: checkboxes + id: checks + attributes: + label: "Pre-Submission Checks / 提交前检查" + description: "Please confirm the following items before submitting. / 提交前请确认以下事项。" + options: + - label: "I searched existing issues and did not find the same documentation problem. / 我已搜索现有 Issue，未发现相同文档问题。" + required: true + - label: "I checked the latest docs site or repository docs pages first. / 我已先检查最新文档站点或仓库文档页面。" + required: true + - type: input + id: page + attributes: + label: "Document Path or URL / 文档路径或链接" + description: "Provide the file path or docs URL if you know it. / 如果知道，请提供文档文件路径或页面链接。" + placeholder: "e.g. docs/zh-CN/core/architecture.md" + validations: + required: true + - type: dropdown + id: doc-issue-type + attributes: + label: "Issue Type / 问题类型" + description: "Choose the primary documentation problem. / 请选择主要问题类型。" + options: + - "Missing content / 缺少内容" + - "Outdated content / 内容过期" + - "Incorrect content / 内容错误" + - "Unclear explanation / 说明不清晰" + - "Missing example / 缺少示例" + - "Translation issue / 翻译问题" + validations: + required: true + - type: textarea + id: current-problem + attributes: + label: "Current Problem / 当前问题" + description: "Describe what is confusing, wrong, or missing. / 说明当前哪里令人困惑、错误或缺失。" + validations: + required: true + - type: textarea + id: expected-docs + attributes: + label: "Expected Improvement / 期望改进" + description: "Describe the improvement you expect. / 说明你期望如何改进。" + validations: + required: true + - type: textarea + id: references + attributes: + label: "Related Code or References / 相关代码或参考资料" + description: "Link related source files, PRs, issues, or external references if helpful. / 如有帮助，请附上相关源码、PR、Issue 或外部参考资料。" diff --git a/.github/ISSUE_TEMPLATE/04-question.yml b/.github/ISSUE_TEMPLATE/04-question.yml new file mode 100644 index 00000000..f9980881 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/04-question.yml @@ -0,0 +1,64 @@ +name: "Question / 使用咨询" +description: "Ask for guidance about usage, behavior, or adoption. / 询问用法、行为或接入方式。" +title: "[Question]: " +body: + - type: markdown + attributes: + value: | + Use this form when your question is specific to GFramework behavior, APIs, or adoption guidance. + + 如果你的问题与 GFramework 的行为、API 或接入方式直接相关，请使用此模板。一般咨询请先查看 README、贡献指南与 docs。 + - type: checkboxes + id: checks + attributes: + label: "Pre-Submission Checks / 提交前检查" + description: "Please confirm the following items before submitting. / 提交前请确认以下事项。" + options: + - label: "I searched existing issues and read the relevant docs first. / 我已先搜索现有 Issue 并阅读相关文档。" + required: true + - label: "This is not a private support request or unrelated general programming question. / 这不是私有支持请求，也不是与本项目无关的泛编程问题。" + required: true + - type: dropdown + id: topic + attributes: + label: "Topic Area / 主题领域" + description: "Choose the area closest to your question. / 请选择最接近问题的主题。" + options: + - "Architecture / 架构" + - "Core APIs / Core API" + - "Game Module / Game 模块" + - "Godot Integration / Godot 集成" + - "Source Generators / 源生成器" + - "Build / Packaging / 构建与打包" + - "Docs / 文档" + - "Other / 其他" + validations: + required: true + - type: textarea + id: goal + attributes: + label: "What Are You Trying To Do? / 你想实现什么？" + description: "Explain your goal before describing the problem. / 请先说明你的目标，再描述遇到的问题。" + placeholder: "I want to... / 我想要……" + validations: + required: true + - type: textarea + id: current-attempt + attributes: + label: "Current Attempt / 当前尝试" + description: "Show what you already tried, including code, docs, or configuration. / 说明你已经尝试过什么，包括代码、文档或配置。" + render: csharp + validations: + required: true + - type: textarea + id: question + attributes: + label: "Specific Question / 具体问题" + description: "Ask the narrowest question that would unblock you. / 提出能真正帮你解阻的最小问题。" + validations: + required: true + - type: textarea + id: environment + attributes: + label: "Relevant Environment / 相关环境" + description: "Include versions or project context if that changes the answer. / 如果版本或项目上下文会影响答案，请补充。" diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..a9fcd691 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: "Search Existing Issues / 搜索现有 Issues" + url: "https://github.com/GeWuYou/GFramework/issues?q=is%3Aissue" + about: "Check whether your topic has already been reported or discussed. / 先确认是否已有相同问题或讨论。" + - name: "Read Contribution Guide / 阅读贡献指南" + url: "https://github.com/GeWuYou/GFramework/blob/main/docs/zh-CN/contributing.md" + about: "Review issue and pull request expectations before submitting. / 提交前先阅读 Issue 与 PR 的协作约定。" + - name: "Browse Documentation / 查看文档" + url: "https://github.com/GeWuYou/GFramework/tree/main/docs/zh-CN" + about: "Read docs, tutorials, and troubleshooting pages first. / 先查看文档、教程与排障页面。" diff --git a/README.md b/README.md index fc7a8fe1..19f04dae 100644 --- a/README.md +++ b/README.md @@ -122,9 +122,11 @@ GFramework.sln 欢迎提交 Issue 与 Pull Request： -1. Fork 本仓库并创建特性分支 -2. 补充必要的测试或文档更新 -3. 提交 PR，描述变更背景、方案与验证结果 +1. 提交 Issue 时请优先选择对应模板：`Bug Report / 缺陷报告`、`Feature Request / 功能建议`、`Documentation / 文档改进`、`Question / 使用咨询` +2. 提交前先搜索现有 Issues，并阅读相关 README、文档或排障页面 +3. Fork 本仓库并创建特性分支 +4. 补充必要的测试或文档更新 +5. 提交 PR，描述变更背景、方案与验证结果 ## 许可证 diff --git a/docs/zh-CN/contributing.md b/docs/zh-CN/contributing.md index d9b92e1d..849c75ae 100644 --- a/docs/zh-CN/contributing.md +++ b/docs/zh-CN/contributing.md @@ -34,40 +34,35 @@ GFramework 是一个开源的游戏开发框架，我们欢迎所有形式的贡 ### 报告问题 -发现 Bug 或有功能建议时，请通过 GitHub Issues 提交： +发现 Bug、有功能建议、文档问题或使用疑问时，请通过 GitHub Issues 提交，并优先使用仓库提供的 Issue Forms： -1. **搜索现有 Issue**：避免重复提交 -2. **使用清晰的标题**：简洁描述问题 -3. **提供详细信息**： - - Bug 报告：复现步骤、预期行为、实际行为、环境信息 - - 功能建议：使用场景、预期效果、可能的实现方案 +- **Bug Report / 缺陷报告**：用于可复现缺陷、异常行为、回归问题 +- **Feature Request / 功能建议**：用于新能力、API 改进、工作流增强 +- **Documentation / 文档改进**：用于文档缺失、过期、错误、示例不足 +- **Question / 使用咨询**：用于与 GFramework 行为、API、接入方式直接相关的问题 -**Bug 报告模板**： +提交前请遵循以下原则： -```markdown -**描述** -简要描述 Bug +1. **先搜索现有 Issue**：避免重复提交 +2. **先查阅文档**：优先阅读相关 README、`docs/` 页面和排障内容 +3. **选择最合适的模板**：让问题更容易分诊和跟进 +4. **补齐最小必要信息**： + - Bug：复现步骤、预期行为、实际行为、环境信息、最小复现或日志 + - 功能建议：问题背景、使用场景、建议方案、替代方案、兼容性影响 + - 文档问题：文档路径、问题类型、当前问题、期望改进 + - 使用咨询：目标、当前尝试、具体问题、相关环境 -**复现步骤** -1. 执行操作 A -2. 执行操作 B -3. 观察到错误 +### Issue 分诊建议 -**预期行为** -应该发生什么 +为便于维护者快速处理，建议按以下方式理解 Issue 类型： -**实际行为** -实际发生了什么 +- **bug**：当前行为与契约、文档或既有能力不一致，且可以描述具体异常或错误结果 +- **enhancement**：现有行为合理但不足，希望新增能力或改进 API / 工作流 +- **documentation**：主要问题在文档内容，而不是运行时行为 +- **question**：主要诉求是澄清如何使用、如何设计或如何接入 +- **needs-repro / needs-info**：当缺少复现仓库、版本信息或关键上下文时，维护者可在分诊时补充使用 -**环境信息** -- GFramework 版本： -- .NET 版本： -- 操作系统： -- Godot 版本（如适用）： - -**附加信息** -日志、截图等 -``` +> 仓库中的标签集合可能会继续演进，但以上分类建议应保持稳定。 ### 提交 Pull Request @@ -830,7 +825,7 @@ npm run docs:build 如果你在贡献过程中遇到问题： -- **GitHub Issues**：提问或报告问题 +- **GitHub Issues**：使用对应模板提问、报告问题或提出建议 - **GitHub Discussions**：参与讨论 - **代码注释**：查看现有代码的注释和文档