上架准备：商店文案、文档同步与 GPL-3.0 开源 - #363
Merged
Merged
Conversation
设计经四轮 grilling 定案，两处难以逆转的取舍记入 ADR。 形态（ADR-0001）：content script 在 document_end 以 shadow DOM 模态弹出， 即用户打开新页面的瞬间，而不是新开标签页。扩展更新由浏览器静默完成， 新标签页会在用户不在场时创建，回来后最容易被顺手关掉。首装欢迎页维持 独立标签页不变，两者共存不合并。 版本（ADR-0002）：不建 CHANGELOG.md、不打 tag，src/changelog/data.ts 里 写了条目的版本即上架版本。本项目每个 fix PR 都 bump 末位版本号，内部版本 变动频繁而只有阶段性完成才上架 —— 此法把「哪个版本值得打扰用户」与「你写 没写更新说明」合并成同一个动作，不可能弹了却没内容或有内容却没弹。校验挂 在 pnpm zip 而非 pnpm build：日常构建时当前版本本就是没有条目的内部版本。 行为：显示出来即算已读（点 X 也算），状态存 sync 独立 key pt-changelog， 不并入 pt-settings 以免被配置导出带走。多标签页并发由 background 串行仲裁， 只放行一个；显示权在发放时即标记已读，渲染失败则 clearSeen 回滚，否则该 上架版本会被永久跳过。iframe、名单中被禁用翻译的站点、开发构建、无条目的 内部版本一律不弹；首装时标记当前版本已读，新用户看到的是欢迎页。 界面色值全部取自 tokens.css 令牌。底部只放大 GitHub 求 star，不显示 star 数以免为一个数字新增 api.github.com 权限。赞赏、文档、社交三块本版隐藏， 以数据驱动表达（数组留空或注释数据行），渲染逻辑照常参与类型检查。 测试：五个纯逻辑 seam 共 25 个用例（版本查询、语言选择、已读状态、本地 预筛、并发仲裁），src/changelog/** 纳入覆盖率门槛 90；modal.ts 属 DOM 渲染，与 src/ui/** 同例外。 Co-Authored-By: zhexuancai-uts <261878103+zhexuancai-uts@users.noreply.github.com>
内容：2.0.66 的条目由一条扩到十条，分新功能 / 改进 / 修复三组。新功能 写对照阅读、六个触发入口、多引擎故障切换与更新提示本身；改进写网页 适配、译文样式、最小权限；修复写三条用户真能感知的：单页应用上自动 冒出译文、shadow DOM 内折叠内容漏翻、导入配置残留本机模型名。 三语各自撰写而非转译 —— 繁体用台港词汇（擴充功能 / 快速鍵 / 匯入 / 預設 / 網路），英文按英文行文重写而不是把中文句式搬过去。 核实后剔除一条：设置页「测试连接」早在 v0.6.1 就存在，#321-#323 只是 把探测逻辑统一到公共入口，属内部重构，写进更新说明会误导用户以为是 新功能。同理，2.0 之后那六十余次提交绝大多数是编排模块与引擎的内部 迁移，用户无从感知，一概不写。 分隔符：标题与描述之间原本硬编码全角冒号，英文用户会看到 「Side-by-side reading：The original…」这样的混搭。改为按语言取值 （中文全角冒号，英文破折号）。此问题由渲染真实数据的预览发现。 Co-Authored-By: zhexuancai-uts <261878103+zhexuancai-uts@users.noreply.github.com>
首装靠 markSeen 挡住更新提示，但 storage 写入是异步的：落盘之前 content script 的 claim 会读到「未读」而拿到显示权，新用户于是在装完 打开的第一个页面上看到「更新内容」弹窗，而它的全屏遮罩还会挡住页面。 窗口很窄，本地 e2e-core 跑两遍都侥幸没触发，但这是竞态赢了而不是不 存在 —— CI 机器负载与本地不同，翻转即表现为偶发红灯，且这类 flaky 查起来很痛。 onInstalled 的监听器现在同步置位内存标志，Service Worker 单线程保证 它跑在任何 claim 消息之前，窗口归零；storage 落盘照旧，SW 回收后由它 接手判定。补两个用例覆盖「标志已置位但 markSeen 尚未落盘」这一瞬。 Co-Authored-By: zhexuancai-uts <261878103+zhexuancai-uts@users.noreply.github.com>
样式：默认从「黄铜色左边线 + 半透明」改为纯半透明，压低译文存在感、 不打断原文阅读节奏；原样式改名 border（中文「左边线」）挪到预设列表 末尾；原 fade 与新 default 效果完全重合，删除。预设总数仍是六种。 存储迁移：选过 fade 的用户，存储里躺着一个不再存在的 id。放行会让 applyStyle 挂上没有任何 CSS 规则的类名 —— 译文变成完全不透明，用户只 会觉得「我明明选了半透明」。merge 是读取路径的单点，迁移放在那里： fade 迁 default（观感不变），认不出的值一律回落 default。 styles/shadow.ts 里有同一套预设的第二份拷贝（:host-context 变体）， 一并同步 —— 漏改会让 shadow DOM 内的译文样式失效，而那正是本扩展 用来对付现代站点的主要手段。 popup：页脚新增「汇报问题」，走 chrome.tabs.create 打开 GitHub 新建 issue 页。不用 window.open —— popup 失焦即关，会连自己一起没掉。 同步更新说明与上架材料：changelog 加两条（默认样式变化、汇报问题 入口），样式清单里的「半透明」改为「左边线」；商店中英描述一并改。 版本 2.0.66 → 2.0.67 —— 2.0.66 的包已经交付过，代码变了必须换号， 否则会出现两个内容不同的同名包。 Co-Authored-By: zhexuancai-uts <261878103+zhexuancai-uts@users.noreply.github.com>
商店说明框不渲染 Markdown，旧文案里的 ## 与 ** 会原样显示成井号 和星号。三份描述改为纯文本，并在文件开头标明简短说明 132 字符、 详细说明 16000 字符的贴入位置。 内容按重构版实际行为重写：六个翻译入口、单段与整页显示模式可分开 设置、引擎按优先级容错切换且跳过不支持目标语言的引擎、Shadow DOM 与同源 iframe 穿透、更新说明只弹一次。新增 description-zh_TW.md。 permissions-justification.md 记录 Privacy practices 分页的填写内容 （英文，审核员会对照 manifest 核验）：storage 的四项用途、 contextMenus 仅注册一个 selection 菜单项、七个引擎端点逐条对应， 以及 Remote code 与 Data usage 两页的选法。改动权限后须同步此文件。 data.ts 顺带统一繁中「左邊線」的用词。 Co-Authored-By: zhexuancai-uts <261878103+zhexuancai-uts@users.noreply.github.com>
样式那行还停在改版前：把「默认」与「半透明」并列成两项，而第六项 「左边线」缺席。默认样式已经就是半透明，原先那套黄铜色边线独立成 「左边线」选项，照实改写。 补一条更新说明与反馈入口 —— 本分支加的功能，特性列表里没有。 测试数字按实测更新：单元 462 → 679，核心 E2E 32 → 36。 Co-Authored-By: zhexuancai-uts <261878103+zhexuancai-uts@users.noreply.github.com>
此前 README 写着「许可尚未确定，保留所有权利」—— 那个状态下别人 连合法 fork 都做不到。现按 GPL-3.0-or-later 开源。 选 copyleft 而非 MIT 是针对翻译扩展被套壳上架这件事：拿去改个图标 重传商店在 MIT 下完全合规，GPL 则要求对方分发时同样开源。 LICENSE 为 FSF 原文（674 行 / 35149 字节），未作任何改动。 package.json 补上此前缺失的 license 字段；三份商店描述在结尾注明许可。 or-later 而非 only 是 FSF 的推荐写法，将来可沿用更新版本的条款。 Co-Authored-By: zhexuancai-uts <261878103+zhexuancai-uts@users.noreply.github.com>
LICENSE 末尾的 How to Apply These Terms 要求逐文件声明 —— 只在 README 和 package.json 写，文件被单独复制出去就不带许可信息了。 75 个文件：65 个 .ts、7 个 .css、3 个 .html。用 SPDX 短标识而非 15 行样板，Linux 内核也是这个写法，工具链可机读。 两处格式上的讲究： - HTML 的注释放在 <!DOCTYPE html> 之后。DOCTYPE 前有内容会让部分 浏览器进 quirks mode。 - popup.css 与 welcome.css 以 @import 开头。CSS 规范只允许 @charset 和注释先于 @import，注释合法，构建产物已核实变量正常内联。 typecheck、679 项单元测试、生产构建均通过。文档类改动，版本号不动。 Co-Authored-By: zhexuancai-uts <261878103+zhexuancai-uts@users.noreply.github.com>
#362 在 GitHub 上以 squash 方式合入，main 得到 627ca57；本分支的 原始提交 26ae94b 的 SHA 与之不同，Git 两边都视为「新增」同名文件， 于是 changelog 模块 7 个文件与 3 份商店描述全部 add/add 冲突。 10 个冲突文件一律取本分支版本。取之前逐个比对过 main 与分支的内容： changelog 七个文件的差异只有本次加的版权头（data.ts 是 6 行新增、 0 行删除），三份商店描述的差异只有结尾那句许可声明。分支版本是 main 版本的超集，没有 main 独有的内容被丢弃。 合并后与 main 的差异仍是 81 文件 / +1165 / -6，与合并前的两点 diff 逐字一致。 Co-Authored-By: zhexuancai-uts <261878103+zhexuancai-uts@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
分支在 #362 合并后继续推进，本 PR 是上架前的收尾：许可证与文档。
主体：项目正式以 GPL-3.0 开源
此前 README 写着「许可尚未确定，保留所有权利」，那个状态下别人连合法 fork 都做不到。
LICENSE：FSF 原文，674 行 / 35149 字节，未作任何改动package.json：补上此前缺失的license字段，取GPL-3.0-or-later（FSF 推荐写法，将来可沿用更新版本的条款）.ts、7 个.css、3 个.html）加 SPDX 版权头，满足 LICENSE 末尾 How to Apply These Terms 的要求选 copyleft 而非 MIT 是针对翻译扩展被套壳上架这件事：拿去改个图标重传商店在 MIT 下完全合规，GPL 则要求对方分发时同样开源。
两处格式上的讲究：HTML 的注释放在
<!DOCTYPE html>之后（DOCTYPE 前有内容会让部分浏览器进 quirks mode）；popup.css与welcome.css以@import开头，CSS 规范只允许@charset和注释先于它，注释合法，构建产物已核实变量正常内联。README 三处修正
关于合并冲突
#362 在 GitHub 上以 squash 方式合入（main 得到
627ca57），本分支的原始提交26ae94b的 SHA 与之不同，Git 两边都视为「新增」同名文件，于是 changelog 模块 7 个文件与 3 份商店描述全部 add/add 冲突。已由
4a8f456合并 main 解决，10 个冲突文件一律取本分支版本。取之前逐个比对过两边内容：changelog 七个文件的差异只有本次加的版权头（data.ts是 6 行新增、0 行删除），三份商店描述的差异只有结尾那句许可声明 —— 分支版本是 main 版本的超集，没有 main 独有的内容被丢弃。合并后与 main 的差异仍是 81 文件 / +1165 / -6，与合并前的两点 diff 逐字一致。验证
pnpm typecheck通过pnpm build通过，产物核实：HTML 的 DOCTYPE 仍在首行，CSS@import正常内联版本号保持 2.0.67 不动 —— 本 PR 是文档与许可类改动。