From c923116b9bfc387a5daf93aa07063bb35a48fc13 Mon Sep 17 00:00:00 2001 From: Cell <1024@lruihao.cn> Date: Wed, 27 Aug 2025 15:07:28 +0800 Subject: [PATCH] chore: standardize GitHub templates and add copilot instructions - Refactor issue templates to English-only format for better international accessibility - Simplify bug report and feature request templates with clearer structure - Add standardized pull request template with contribution guidelines - Disable blank issues and update documentation links in issue config - Add comprehensive copilot instructions with coding standards and best practices --- .github/ISSUE_TEMPLATE/bug-report.yml | 74 ++--- .github/ISSUE_TEMPLATE/config.yml | 13 +- .github/ISSUE_TEMPLATE/feature-request.yml | 55 ++-- .github/PULL_REQUEST_TEMPLATE.md | 24 ++ .github/copilot-instructions.md | 320 +++++++++++++++++++++ 5 files changed, 423 insertions(+), 63 deletions(-) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/copilot-instructions.md diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml index 3f6f88d5..8b3424b3 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.yml +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -1,51 +1,55 @@ -name: "Bug Report 错误报告" -description: "Create a bug report 创建一个错误报告" -title: "[BUG] Some problem ..." -labels: ["bug"] +name: Bug Report +description: Create a report to help us improve +title: "[Bug report] " body: - - type: textarea - id: describe + - type: markdown attributes: - label: Describe the bug 描述你遇到的错误 - description: | - A clear and concise description of what the bug is. - 一段简短的对于你遇到的错误的描述。 + value: | + Thanks for taking the time to fill out this bug report! - type: textarea - id: expected + id: bug-description attributes: - label: Expected behavior 期待的行为 - description: | - A clear and concise description of what you expected to happen. - 一段简短的对于你期待的行为的描述。 - - type: textarea - id: screenshots + label: Description + description: A clear and concise description of what the bug is. If applicable, add screenshots to help explain your problem. If you intend to submit a PR for this issue, tell us in the description. Thanks! + placeholder: Bug description + validations: + required: true + - type: input + id: reproduction attributes: - label: Screenshots 屏幕截图 - description: | - If applicable, add screenshots to help explain your problem. - 如果可以的话，提供屏幕截图对解决问题很有帮助。 + label: Reproduction + description: Please provide a link to a repo that can reproduce the problem you ran into. A [minimal reproduction](https://stackoverflow.com/help/minimal-reproducible-example) is required. + placeholder: Reproduction + validations: + required: true + - type: dropdown + id: installation-method + attributes: + label: Installation Method + description: Select the installation method you used. + options: + - Hugo Module + - Git Submodule + - Git Clone + - Manual + - Other + validations: + required: true - type: textarea id: environment attributes: - label: Build Environment 构建环境 + label: Build Environment description: | Please try to use Hugo **extended** version before opening the issue. - 请在创建 issue 之前尝试使用 Hugo **extended** 版本。 placeholder: | - - OS: [e.g. Windows 10, macOS, Ubuntu] - Theme version/commit [e.g. 0.2.0, 2ccba79] - - Hugo version [e.g. 0.69.0] - - type: textarea - id: preview - attributes: - label: Preview Environment 预览环境 - placeholder: | - - OS: [e.g. Windows 10, macOS, Ubuntu, iOS, Android] - - Browser [e.g. Chrome, Safari, Firefox] + - Hugo version [e.g. 0.147.0] + - OS: [e.g. Windows 10, macOS, Ubuntu] + validations: + required: true - type: textarea id: additional attributes: - label: Additional Information 补充信息 + label: Additional Information description: | - Configuration files or front matter code ... - 配置文件或者前置参数的代码…… + Configuration files or front matter code snippets that may help us understand the issue. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 2193e07b..cab08575 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,9 +1,8 @@ -blank_issues_enabled: true +blank_issues_enabled: false contact_links: - - name: Questions 问题讨论 + - name: Questions url: https://github.com/hugo-fixit/FixIt/discussions/new - about: Please ask questions in Discussion. 请在讨论中提问。 - - - name: Theme Documentation 主题文档 - url: https://fixit.lruihao.cn/documentation/ - about: Please read the documentation carefully. 请先仔细阅读主题文档。 + about: Please ask questions in Discussion. + - name: Theme Documentation + url: https://fixit.lruihao.cn/ + about: Please read the documentation carefully. diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml index add0d8e2..af3c006f 100644 --- a/.github/ISSUE_TEMPLATE/feature-request.yml +++ b/.github/ISSUE_TEMPLATE/feature-request.yml @@ -1,22 +1,35 @@ -name: "Feature request 功能请求" -description: "Suggest an idea for this project 为这个项目提供一个建议" -title: "[FEATURE] Some feature" -labels: ["enhancement"] +name: Feature Request +description: Suggest an idea for this project +title: "[Feature request] " body: - - type: textarea - id: describe - attributes: - label: Describe the feature you want 描述你的功能需求 - description: | - Please submit new issues for different features. - 请针对不同的功能建议提交新的 issue。 - placeholder: | - I recommend adding this feature ... - 我希望添加这样的一个功能…… - - type: textarea - id: reference - attributes: - label: Useful reference 有价值的参考 - description: | - If available, provide useful links to fulfill the feature. - 如果可以的话，提供实现这个功能的相关参考链接。 + - type: markdown + attributes: + value: | + Thanks for your interest in the project and taking the time to fill out this feature request! + - type: textarea + id: feature-description + attributes: + label: Clear and concise description of the problem + description: As a user or developer using FixIt, what feature your want in details. If you intend to submit a PR for this issue, tell us in the description. Thanks! + placeholder: Feature description + validations: + required: true + - type: textarea + id: suggested-solution + attributes: + label: Suggested solution + description: We could provide following implementation... + placeholder: Suggested solution + validations: + required: true + - type: textarea + id: alternative + attributes: + label: Alternative + description: Clear and concise description of any alternative solutions or features you've considered. + placeholder: Alternative solution + - type: textarea + id: additional-context + attributes: + label: Additional context + description: Any other context or screenshots about the feature request here. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..a05fd08d --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,24 @@ + + +### Before submitting the PR, please make sure you do the following + +- [ ] Read the [Contributing Guidelines](https://github.com/hugo-fixit/FixIt/blob/main/CONTRIBUTING.md). +- [ ] Provide a description in this PR that addresses **what** the PR is solving. If this PR is going to solve an existing issue, please reference the issue (e.g. `close #123`). + +### What is the purpose of this pull request? + +- [ ] Bug fix +- [ ] New feature +- [ ] Other + +### Description + + + +### Screenshots + + + +**Before** + +**After** diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..50fe7634 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,320 @@ +# FixIt 编码标准和指导原则 + +本文档定义了 FixIt 主题项目的编码标准、最佳实践和开发指导原则。所有贡献者和 AI 助手在参与项目开发时都应遵循这些规范。 + +## 项目概述 + +FixIt 是一个面向 Hugo 静态网站生成器的现代化、响应式主题。项目基于以下技术栈： + +- **Hugo**: 静态网站生成器（≥ 0.147.7） +- **SCSS**: CSS 预处理器，用于样式开发 +- **JavaScript**: ES6+ 标准，用于前端交互功能 +- **Go Templates**: Hugo 模板引擎 +- **Node.js**: 开发环境和构建工具 +- **pnpm**: 包管理器 + +## 目录结构约定 + +``` +FixIt/ +├── archetypes/ # 内容模板 +├── assets/ # 主题资源文件 +│ ├── css/ # SCSS 样式文件 +│ ├── js/ # JavaScript 文件 +│ ├── images/ # 图像资源 +│ └── lib/ # 第三方库 +├── demo/ # 演示站点 +├── i18n/ # 国际化翻译文件 +├── layouts/ # Hugo 模板文件 +│ ├── _markup/ # Hugo 渲染钩子 +│ ├── _partials/ # 可复用模板组件 +│ └── _shortcodes/ # 自定义短代码 +├── static/ # 静态文件 +├── test/ # 测试站点内容 +└── hugo.toml # 主题默认配置 +``` + +## SCSS/CSS 编码规范 + +### 文件组织结构 + +1. **主入口文件**: `assets/css/style.scss` +2. **变量文件**: `assets/css/_variables.scss` - 全局变量定义 +3. **覆写文件**: `assets/css/_override.scss` - 用户自定义覆写 +4. **组织结构**: + - `_core/`: 核心样式（基础、布局、媒体查询等） + - `_mixin/`: SCSS mixins 和函数 + - `_page/`: 页面特定样式 + - `_partials/`: 组件样式 + - `_shortcodes/`: 短代码样式 + +### 命名约定 + +1. **CSS 类名**: 使用 BEM 方法论或语义化命名 + + ```scss + .header-desktop {} + .menu-item {} + .single-title {} + .post-tag {} + ``` + +2. **SCSS 变量**: 使用连字符分隔，语义化命名 + + ```scss + $global-font-family: system-ui, sans-serif; + $code-background-color: #f6f8fa; + $header-height: 3.5rem; + ``` + +3. **CSS 自定义属性**: 使用前缀约定 + + ```scss + $prefix: fi-; + $rootPrefix: --fi-; + ``` + +### 样式组织原则 + +1. **主题切换支持**: 使用数据属性选择器 + + ```scss + .element { + color: $global-font-color; + + [data-theme='dark'] & { + color: $global-font-color-dark; + } + } + ``` + +2. **Mixin 使用**: 提高代码复用性 + + ```scss + @include border-radius($global-border-radius); + @include transition(all 0.2s ease); + @include blur; + ``` + +### 代码质量要求 + +1. **缩进**: 使用 2 个空格 +2. **注释**: 为复杂逻辑添加注释 +3. **颜色**: 使用变量而非硬编码颜色值 +4. **单位**: 优先使用相对单位（rem、em、%） + +## JavaScript 编码规范 + +### 代码风格 + +1. **ES6+ 标准**: 使用现代 JavaScript 语法 +2. **模块化**: 使用 ES6 模块系统 + +### 文件组织 + +1. **主题核心**: `assets/js/theme.js` - 主题核心逻辑 +2. **工具函数**: `assets/js/util.js` - 通用工具函数 +3. **特定功能**: 按功能划分独立模块 + +### 编码实例 + +```javascript +// 使用 ES6 类 +export default class Util { + /** + * 工具函数示例 + * @param {String} text 要复制的文本 + * @returns {Promise} 返回 Promise + */ + copyText(text) { + if (navigator.clipboard) { + return navigator.clipboard.writeText(text); + } + // 降级方案... + } +} + +// 主题类组织 +class FixIt { + constructor() { + this.config = window.config; + this.util = new Util(); + } + + init() { + this.initTheme(); + this.initComponents(); + } +} +``` + +### 最佳实践 + +1. **错误处理**: 使用 try-catch 处理异常 +2. **异步操作**: 优先使用 async/await +3. **事件处理**: 合理使用事件委托 +4. **性能优化**: 避免不必要的 DOM 操作 + +## Hugo 模板规范 + +### 模板组织 + +1. **布局模板**: `layouts/` 目录下的主要模板 +2. **局部模板**: `layouts/_partials/` 下的可复用组件 +3. **短代码**: `layouts/_shortcodes/` 下的内容短代码 + +### 编码约定 + +1. **变量命名**: 使用驼峰命名法 + + ```go-html-template + {{- $footerConfig := .Site.Params.footer -}} + {{- $fingerprint := .Site.Store.Get "fingerprint" -}} + ``` + +2. **注释规范**: 使用 Hugo 注释语法 + + ```go-html-template + {{- /* 这是模板注释 */ -}} + {{- /* + 多行注释 + 可以跨越多行 + */ -}} + ``` + +3. **条件判断**: 清晰的条件结构 + + ```go-html-template + {{- if ne $config.enable false -}} + + {{- end -}} + ``` + +4. **循环遍历**: 合理使用 range + + ```go-html-template + {{- range $index, $value := .Site.Languages -}} + + {{- end -}} + ``` + +### 国际化处理 + +1. **翻译函数**: 使用 `T` 函数 + + ```go-html-template + {{ T "header.switchTheme" }} + ``` + +2. **多语言支持**: 考虑多语言环境 + + ```go-html-template + {{- if hugo.IsMultilingual -}} + + {{- end -}} + ``` + +## 开发工作流程 + +### 环境设置 + +1. **前置要求**: + - Node.js (≥ 20.0.0) + - Hugo Extended (≥ 0.147.7) + - pnpm (包管理器) + +2. **开发命令**: + + ```bash + pnpm dev # 启动开发服务器 + pnpm test # 运行测试环境 + pnpm build # 构建 Demo + ``` + +### 代码质量 + +1. **代码审查**: 提交前进行自我审查 +2. **测试验证**: 在多个环境中测试功能 +3. **文档更新**: 必要时更新相关文档 +4. **向后兼容**: 确保更改不破坏现有功能 + +### Git 提交规范 + +遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范： + +``` +feat: 新增功能 +fix: 修复 bug +docs: 文档更新 +style: 代码格式调整 +refactor: 代码重构 +test: 测试相关 +chore: 构建过程或工具相关 +``` + +## 性能优化指导 + +### CSS 性能 + +1. **选择器优化**: 避免过深的嵌套 +2. **媒体查询**: 合理组织响应式断点 +3. **动画优化**: 使用 transform 和 opacity +4. **资源压缩**: 生产环境启用压缩 + +### JavaScript 性能 + +1. **延迟加载**: 非关键脚本使用 defer +2. **事件优化**: 合理使用防抖和节流 +3. **内存管理**: 及时清理事件监听器 +4. **模块化**: 按需加载功能模块 + +### Hugo 模板性能 + +1. **缓存策略**: 合理使用 Hugo 缓存机制 +2. **资源处理**: 优化图片和静态资源 +3. **构建优化**: 减少不必要的模板处理 + +## 可访问性要求 + +1. **语义化 HTML**: 使用正确的 HTML 标签 +2. **ARIA 属性**: 为复杂组件添加 ARIA 支持 +3. **键盘导航**: 确保键盘可访问性 +4. **颜色对比**: 满足 WCAG 对比度要求 +5. **屏幕阅读器**: 提供适当的文本替代 + +## 浏览器兼容性 + +1. **目标浏览器**: 支持现代浏览器 +2. **渐进增强**: 基础功能向下兼容 +3. **特性检测**: 使用特性检测而非浏览器检测 +4. **Polyfill**: 必要时提供 polyfill 支持 + +## 安全考虑 + +1. **XSS 防护**: 正确处理用户输入 +2. **CSRF 保护**: 表单提交安全 +3. **内容安全**: 合理设置 CSP 策略 +4. **依赖安全**: 定期更新依赖包 + +## 文档要求 + +1. **代码注释**: 复杂逻辑必须注释 +2. **API 文档**: 公共方法需要文档 +3. **使用示例**: 提供清晰的使用示例 +4. **更新日志**: 重要更改记录在 CHANGELOG + +## 第三方库管理 + +1. **依赖选择**: 优先选择轻量、维护活跃的库 +2. **版本管理**: 及时更新安全补丁 +3. **许可证**: 确保许可证兼容性 +4. **定制化**: 必要时进行本地化修改 + +## 贡献指导 + +1. **讨论优先**: 重大更改前先讨论 +2. **小步迭代**: 避免大规模重构 +3. **测试覆盖**: 新功能需要充分测试 +4. **文档同步**: 功能和文档同时更新 + +遵循这些编码标准将有助于维护代码质量，提高开发效率，并确保项目的长期可维护性。