From 5370bd457c3d6aca63f1ac4f4be19e1c45512a27 Mon Sep 17 00:00:00 2001 From: gis2all <1262057294@qq.com> Date: Tue, 15 Sep 2026 21:23:47 +0800 Subject: [PATCH] docs: add code of conduct, contributing guide and issue templates Add repository community standards under .github/: Contributor Covenant 2.1 code of conduct, contributing guide, security policy, issue forms and a pull request template matching the CI gates. --- .github/CODE_OF_CONDUCT.md | 89 ++++++++++++++++++++++ .github/CONTRIBUTING.md | 60 +++++++++++++++ .github/ISSUE_TEMPLATE/bug_report.yml | 60 +++++++++++++++ .github/ISSUE_TEMPLATE/feature_request.yml | 33 ++++++++ .github/PULL_REQUEST_TEMPLATE.md | 26 +++++++ .github/SECURITY.md | 28 +++++++ 6 files changed, 296 insertions(+) create mode 100644 .github/CODE_OF_CONDUCT.md create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/SECURITY.md diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..55714c5 --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,89 @@ +# 贡献者公约(行为准则) + +本准则适用于「FocusFlow」仓库及其社区的所有场合:Issue、Pull Request、代码评审等;参与这些场合即表示同意遵守本准则。 + +> 本文件采用 [Contributor Covenant][homepage] 2.1 版简体中文译本,仅在「监督」一节填入本项目的举报方式。 + +## 我们的承诺 + +身为社区成员、贡献者和领袖,我们承诺使社区参与者不受骚扰,无论其年龄、体型、可见或不可见的缺陷、族裔、性征、性别认同和表达、经验水平、教育程度、社会与经济地位、国籍、相貌、种族、种姓、肤色、宗教信仰、性倾向或性取向如何。 + +我们承诺以有助于建立开放、友善、多样化、包容、健康社区的方式行事和互动。 + +## 我们的准则 + +有助于为我们的社区创造积极环境的行为例子包括但不限于: + +- 表现出对他人的同情和善意 +- 尊重不同的主张、观点和感受 +- 提出和大方接受建设性意见 +- 承担责任并向受我们错误影响的人道歉 +- 注重社区共同诉求,而非个人得失 + +不当行为例子包括: + +- 使用情色化的语言或图像,及性引诱或挑逗 +- 嘲弄、侮辱或诋毁性评论,以及人身或政治攻击 +- 公开或私下的骚扰行为 +- 未经他人明确许可,公布他人的私人信息,如物理或电子邮件地址 +- 其他有理由认定为违反职业操守的不当行为 + +## 责任和权力 + +社区领袖有责任解释和落实我们所认可的行为准则,并妥善公正地对他们认为不当、威胁、冒犯或有害的任何行为采取纠正措施。 + +社区领导有权力和责任删除、编辑或拒绝或拒绝与本行为准则不相符的评论(comment)、提交(commits)、代码、维基(wiki)编辑、议题(issues)或其他贡献,并在适当时机知采取措施的理由。 + +## 适用范围 + +本行为准则适用于所有社区场合,也适用于在公共场所代表社区时的个人。 + +代表社区的情形包括使用官方电子邮件地址、通过官方社交媒体帐户发帖或在线上或线下活动中担任指定代表。 + +## 监督 + +辱骂、骚扰或其他不可接受的行为可通过邮箱 1262057294@qq.com 向仓库维护者(@gis2all)报告。所有投诉都将得到及时和公平的审查和调查。 + +所有社区领袖都有义务尊重任何事件报告者的隐私和安全。 + +## 处理方针 + +社区领袖将遵循下列社区处理方针来明确他们所认定违反本行为准则的行为的处理方式: + +### 1. 纠正 + +**社区影响**:使用不恰当的语言或其他在社区中被认定为不符合职业道德或不受欢迎的行为。 + +**处理意见**:由社区领袖发出非公开的书面警告,明确说明违规行为的性质,并解释举止如何不妥。或将要求公开道歉。 + +### 2. 警告 + +**社区影响**:单个或一系列违规行为。 + +**处理意见**:警告并对连续性行为进行处理。在指定时间内,不得与相关人员互动,包括主动与行为准则执行者互动。这包括避免在社区场所和外部渠道中的互动。违反这些条款可能会导致临时或永久封禁。 + +### 3. 临时封禁 + +**社区影响**: 严重违反社区准则,包括持续的不当行为。 + +**处理意见**: 在指定时间内,暂时禁止与社区进行任何形式的互动或公开交流。在此期间,不得与相关人员进行公开或私下互动,包括主动与行为准则执行者互动。违反这些条款可能会导致永久封禁。 + +### 4. 永久封禁 + +**社区影响**:行为模式表现出违反社区准则,包括持续的不当行为、骚扰个人或攻击或贬低某个类别的个体。 + +**处理意见**:永久禁止在社区内进行任何形式的公开互动。 + +## 参见 + +本行为准则改编自 [Contributor Covenant][homepage] 2.1 版, 参见 [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]。 + +社区处理方针灵感来源于 [Mozilla's code of conduct enforcement ladder][Mozilla CoC]。 + +有关本行为准则的常见问题的答案,参见 [https://www.contributor-covenant.org/faq][FAQ]。 其他语言翻译参见 [https://www.contributor-covenant.org/translations][translations]。 + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..7890290 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,60 @@ +# 贡献指南 + +欢迎为「FocusFlow」贡献代码、文档和想法。无论是修 bug、补测试、提建议还是改文档,请先阅读本指南与 [README](../README.md)。 + +## 开发环境 + +需要 Windows 10/11 x64 与 Node.js 22(含 npm),安装依赖使用 `npm ci`。 + +| 用途 | 命令 | +| --- | --- | +| 桌面开发态 | `npm run dev` | +| 网页模式 | `npm run web:start` | +| 网页开发态 | `npm run web:dev` | +| 单元测试 | `npm test` | +| 覆盖率 | `npm run test:coverage` | +| 打包 | `npm run package` | + +完整命令与平台边界见 [CLAUDE.md](../CLAUDE.md),用户可见能力见 [README](../README.md)。 + +## 提交前检查 + +CI 会执行与下面相同的门禁(Windows / PowerShell 语义,不要用 bash 风格 `&&`),请先在本地跑通: + +```powershell +npm ci +npm run test:coverage +npm run build +npm run test:e2e +npm run package +npm run test:package-smoke +``` + +- 覆盖率门禁只统计纯逻辑模块(`core/`、`shared/`、`main/services/`、`main/repositories/`、`main/adapters/sqlite/`、`server/rpc.ts` 等),阈值 statements / lines 90、functions 85、branches 70;壳层与视图由 E2E 覆盖。 +- 修改计时、统计、任务等业务规则时,同步补充或更新对应单元测试。 +- 修改交互、窗口、托盘、通知、持久化等壳层行为时,补充或更新 Playwright E2E(`npm run test:e2e`)。 +- 运行 `npm run package` 前先退出所有从 `output/release/` 启动的 FocusFlow 实例,否则打包会因目录被占用报 `EBUSY`。 +- 不要提交 `output/`、`coverage/`、`node_modules/`、`*.sqlite*`、`docs/`、`.learnings/` 等产物与本地目录。 + +## 修改边界 + +- 业务规则放 `core/` 或 `main/services/`,不要塞回 React 组件。 +- Renderer 只通过 preload 暴露的 `window.focusFlow` 访问桌面能力,不直接触碰 Electron 主进程对象。 +- Web 端复用 `core/` 与 `main/services/`,通过 `server/rpc.ts` 分发请求,并复用主进程的运行时校验。 +- IPC channel、shared 类型、数据库 schema、打包产物命名是稳定边界,改动前先确认影响面。 +- 主进程边界对入参做运行时校验,不要把 TypeScript 类型当作不可信 renderer 数据的运行时保证。 + +完整规则见 [CLAUDE.md](../CLAUDE.md)。 + +## 分支与 PR + +1. 从最新 `main` 切出分支,命名如 `codex/fix-xxx`、`feat/xxx`。 +2. 完成修改并通过本地检查清单。 +3. 推送分支并创建 PR,按 [PR 模板](./PULL_REQUEST_TEMPLATE.md) 填写。 +4. 等待 CI 通过和审核;合入 `main` 后由维护者打包并创建 Release。 + +## 问题与安全 + +- Bug 和功能建议请用仓库的 Issue 模板提交。 +- 安全漏洞不要公开发布,请按 [SECURITY.md](./SECURITY.md) 私下报告。 +- 参与 Issue、Pull Request、讨论时请遵守[行为准则](./CODE_OF_CONDUCT.md)。 diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..efc80d2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,60 @@ +name: Bug 报告 +description: 提交一个可复现的缺陷 +title: "[Bug] " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + 感谢报告问题。请尽量完整填写以下信息,便于快速定位和复现。 + - type: textarea + id: description + attributes: + label: 问题描述 + description: 实际发生了什么?预期应该是什么? + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: 复现步骤 + description: 从启动应用开始的最小复现路径。 + placeholder: | + 1. 启动 FocusFlow + 2. 点击 … + 3. 看到 … + validations: + required: true + - type: dropdown + id: environment + attributes: + label: 运行形态 + description: 在哪种形态下复现? + options: + - 桌面开发态(npm run dev) + - 网页模式(npm run web:start 或 web:dev) + - 安装版 focusflow-setup.exe + - 便携版 focusflow-single.exe + - 其他(请在补充信息里说明) + validations: + required: true + - type: input + id: version + attributes: + label: 版本 + description: 应用版本,或 git log -1 --oneline 的结果。 + - type: input + id: system + attributes: + label: 系统环境 + description: 例如 Windows 11 24H2 x64 + - type: textarea + id: logs + attributes: + label: 日志与截图 + description: 终端报错、electron-log 输出、浏览器控制台日志或截图(可直接粘贴图片)。 + - type: textarea + id: extra + attributes: + label: 补充信息 + description: 其他可能有用的上下文(可选)。 diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..caccea4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,33 @@ +name: 功能建议 +description: 提出新功能或改进建议 +title: "[Feature] " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + 描述你希望解决的实际问题,而不是直接给出实现方案,便于一起讨论。 + - type: textarea + id: motivation + attributes: + label: 动机 / 要解决的问题 + description: 为什么需要这个功能?现在哪里不方便? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: 建议方案 + description: 你期望的交互或实现方式。 + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: 备选方案 + description: 其他可以考虑的做法(可选)。 + - type: textarea + id: acceptance + attributes: + label: 验收标准 + description: 完成该功能后应能观察到的效果(可选)。 diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..e2802ac --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,26 @@ +## 概述 + + + +## 关联 Issue + + + +## 变更内容 + +- [ ] 变更点 1 +- [ ] 变更点 2 + +## 检查清单 + +- [ ] `npm run test:coverage` 通过(Vitest 与覆盖率门禁) +- [ ] `npm run build` 通过(tsc 与 electron-vite) +- [ ] `npm run test:e2e` 通过(Playwright 与真实 Electron) +- [ ] `npm run package` 通过(安装包与便携版) +- [ ] `npm run test:package-smoke` 通过(打包态烟测) +- [ ] 未提交 `output/`、`coverage/`、`*.sqlite*` 等产物与本地数据 +- [ ] IPC、shared 类型、数据库 schema、打包命名的改动已在描述中说明影响面 + +## 截图 + + diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 0000000..0ba2977 --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,28 @@ +# 安全策略 + +## 支持范围 + +本项目是个人开发的桌面应用,安全修复只针对最新 `main` 分支与 [Releases](https://github.com/gis2all/focus-flow/releases) 中的最新版本;更早的版本不再单独维护。 + +## 报告漏洞 + +请勿在 Issue、PR 或公开讨论中透露漏洞细节。 + +推荐通过 GitHub 私有漏洞报告(Private vulnerability reporting)提交: + +1. 打开仓库 **Security** 页签; +2. 点击 **Report a vulnerability**; +3. 按提示填写受影响版本、复现步骤和影响评估。 + +## 响应承诺 + +- 7 天内确认收到报告; +- 确认有效的问题在 30 天内给出修复或缓解方案; +- 修复合入后,在发布说明中说明。 + +## 主要风险面 + +- 分发渠道:安装包与便携版通过 GitHub Releases 发布,请确认下载来源为本仓库;`win-unpacked/` 仅用于开发者烟测,不作为正式下载项。 +- 渲染层:Renderer 运行在 sandbox 中,桌面能力只经 `preload/` 的 `contextBridge`(`window.focusFlow`)暴露;IPC 入参在主进程边界做运行时校验。 +- 本地 Web 模式:`server/` 默认只监听 `127.0.0.1` 且无鉴权,对外暴露前必须自行加认证与 HTTPS。 +- 本地数据:默认保存在本机(`%APPDATA%` 下的 `focusflow.sqlite`),项目不依赖账号或云同步,也没有应用内自动更新通道。