# 贡献指南

**非常欢迎各位劳斯们贡献代码！！！** 不管是干啥都很感谢w

下面是一些约定，主要是为了协作的时候少踩坑、少返工

---

## 报告 Bug / 提建议

1. 先在 [Issues](https://github.com/Gledery/frostart/issues) 里搜一下，确认没有人提过
2. 如果没有，请新建一个 Issue，选对应的模板（Bug 报告 / 功能建议），填好内容就行
3. 截图、录屏、复现步骤越详细越好，但也别有压力

---

## 贡献代码的流程

### 1. 先确认改动类型

| 改动类型 | 例子 | 流程 |
|---------|------|------|
| **小型 / 低风险** | 修 bug、抽离重复函数、加注释、改样式 | 直接提 PR |
| **中型 / 需同步** | 新增功能、调整组件逻辑、改动多个文件 | 建议**先在 Issue 里说明思路**，收到回复后再动手 |
| **大型 / 架构级** | IIFE 隔离、循环依赖重构、ES Module 迁移 | **必须先在 Issue 里讨论并达成共识**，但是不建议私自修改，因为 |

> 大改动容易和项目维护者正在做的迭代冲突导致其中一个作废，先聊一下能避免很多问题

### 2. Fork & 分支

```bash
# Fork 之后 clone 你自己的仓库
git clone https://github.com/<你的用户名>/frostart.git
cd frostart

# 从 main 拉一个新分支，名字看改动内容起，比如：
git checkout -b feat/custom-wallpaper
git checkout -b refactor/utils-extraction
```

### 3. 开发 & 测试

- 改完之后本地加载到浏览器测一下（`chrome://extensions/` → 开发者模式 → 加载已解压的扩展程序）
- 如果改动涉及多个功能模块，**请逐个手动验证**
- 确保没有引入新的 `console.error`。

### 4. 提交（Commit）

- **一个 commit 只做一件事**，不要把 bug 修复和功能新增混在一起
- 提交信息格式：`类型: 简述`，类型包括 `fix`（修 bug）、`feat`（新功能）、`refactor`（重构）、`docs`（文档）、`style`（样式）、`chore`（杂项）

```
fix: 修复搜索框在某些分辨率下被遮挡的问题
feat: 新增必应壁纸标题显示
refactor: 抽离 escapeHtml/clamp 到 js/utils/
docs: 补充 README 浏览器兼容说明
style: 调整设置面板的间距
chore: 更新 .gitignore
```

- 如果需要关联 Issue，在提交信息末尾加 `#Issue编号`，比如 `fix: 修复时钟闪烁 #1`

### 5. 发起 PR

- 向 `main` 分支发起 Pull Request
- PR 描述请参照模板填写：**改了什么、影响哪些组件/函数、测试情况**。不用写很长，说清楚就行
- 如果 PR 还没做完、想先让人看看，可以在标题前加 `[WIP]`

---

## 代码风格

这个项目没有用 lint 工具，但请尽量遵守以下约定：

### JavaScript

- 大括号不换行：
  ```javascript
  if (ok) {
      doSomething();
  }
  ```
- 函数 / 变量用 `camelCase`，常量用 `UPPER_SNAKE_CASE`。
- 每个模块文件顶部写**职责注释块**（参考 `core.js` 第 1-12 行的格式）：
  ```
  /* =========================================
     文件名.js  —  一句话职责
     职责：具体列举
     加载顺序：xxx → xxx
     ========================================= */
  ```
- 逻辑复杂的地方写注释，简单的不需要

### CSS

- 设计令牌统一放在 `tokens.css`，组件样式放 `components.css`，页面专属放 `pages.css`。
- 自定义属性用 `--kebab-case`。

### 不要做的事

- **不要**引入前端框架 / 构建工具（这是有意的决定，保持原生）。
- **不要**修改 `newtab.html` 中 `<script>` 标签的加载顺序，除非确认了不会破坏依赖链。
- **不要**在 PR 里夹带与改动无关的格式化变更。

---

## 关于 changelog 和版本号

- 如果你的改动涉及用户可感知的变化，请在 PR 里注明，维护者会负责更新 `js/changelog.js` 和 `manifest.json` 的版本号。
- **请绝对不要自己改 manifest 版本号**这将被所有用户识别并且推送错误的更新，如果是预览的完整版本更新请另外说明
- changelog 条目统一使用「类别：简述」格式，类别包括：

  | 类别 | 含义 | 示例 |
  |------|------|------|
  | **新增** | 新功能、新文件 | 新增：存储空间用量指示器 |
  | **修复** | Bug 修复 | 修复：Toast 入场动画问题 |
  | **优化** | 性能或体验提升 | 优化：时钟性能，缓存 DOM 引用 |
  | **变更** | 对已有行为或外观的修改 | 变更：光斑跟随渐变从按钮改为开关 |
  | **重构** | 代码结构调整，不改变行为 | 重构：app.js 拆分为四个模块 |
  | **清理** | 删除无用代码或文件 | 清理：删除没人引用的 converter.js |
  | **规范化** | 统一格式或规范 | 规范化：统一所有 JS 文件头部注释 |
  | **样式** | 纯视觉设计调整 | 样式：头像从圆形改为圆角矩形 |
  | **移除** | 移除功能或元素 | 移除：打开设置时的背景变暗遮罩 |

---

## 反馈

- 在 [Issues](https://github.com/Gledery/frostart/issues) 提问。
- 或者 B 站私信：[灰鸢 Gledery](https://space.bilibili.com/3461577804089941)

---

感谢你读到这里，一起帮助 Frostart 無限進步吧 (。・ω・。)