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
2026-08-24 15:28:57 +00:00 · 2025-08-27 15:07:28 +08:00
parent 0cc7882d22
commit c923116b9b
5 changed files with 423 additions and 63 deletions
@@ -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.
@@ -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.
@@ -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.
@@ -0,0 +1,24 @@
+<!-- Thank you for contributing! -->
+
+### Before submitting the PR, please make sure you do the following <!-- (put an "X" next to an item) -->
+
+- [ ] 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? <!-- (put an "X" next to an item) -->
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Other
+
+### Description
+
+<!-- Please insert your description here and provide especially info about the "what" this PR is solving -->
+
+### Screenshots
+
+<!-- If your PR includes UI changes, please provide before/after screenshots. If there are any other images that add context to the PR, add them here as well -->
+
+**Before**
+
+**After**
@@ -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. **文档同步**: 功能和文档同时更新
+
+遵循这些编码标准将有助于维护代码质量，提高开发效率，并确保项目的长期可维护性。