企业官网建设流程全解析

• 前端

Beaker（An Experimental Peer-to-Peer Web Browser）的桌面端 UI 大量基于 Web Components 构建，并将 lit-element 完整 vendor 进仓库作为前端基础设施。本文以仓库内嵌的 app/userland/app-stdlib/vendor/lit-element/CONTRIBUTING.md 为骨架，系统讲解 lit-element 的贡献渠道、Bug 提交流程、Pull Request 规范、基于 polymer-cli 的单元测试运行方式，并结合 Beaker 仓库内真实源码佐证其落地形态。读完本文，你将掌握一套可复用的"上游库协作 + 本地化测试"工作流，并能理解 Beaker 内部组件（如beaker-toast）与 lit-element 的调用关系。

一、文档定位：一份随库内嵌的开源协作指南

CONTRIBUTING.md是上游 lit-element 项目的贡献指南，随依赖被完整 vendor 到仓库的 app/userland/app-stdlib/vendor/lit-element/ 目录下。从仓库证据看，该目录包含完整的构建产物：lit-element.js入口、lib/updating-element.js、lib/decorators.js、lib/css-tag.js，以及内嵌的lit-html/子库（含 13 个指令与渲染核心）。lit-element.js 中明确写入litElementVersions.push('2.0.1')，结合 CHANGELOG.md 可确认 Beaker 携带的是 lit-element 2.0.1 版本。

这份文档面向的对象是"想要向 lit-element 上游贡献代码"的开发者，但它描述的协作纪律（CLA、Issue 模板、测试先行）对任何使用 lit-element 构建组件的团队同样成立。因此本文在保留原文档全部实操步骤的同时，会同步给出 Beaker 仓库内的消费示例，让读者既懂"怎么贡献上游"，也懂"怎么在本地用好它"。

二、贡献渠道与仓库地图：先搞清楚代码该提交到哪里

Polymer/lit-element 生态是高度组件化的，因此代码分散在多个仓库，贡献前必须先定位正确归属：

• 核心库：Polymer 主仓库，核心库相关的 Bug 与 PR 都应提交到Polymer/polymer；
• 官方元素（PolymerElements 组织）：团队维护的各类元素仓库，例如paper-button就在其独立仓库中维护，元素级问题直接提交到对应元素仓库；
• Google 元素（GoogleWebComponents 组织）：由 Google 内多个团队维护，问题与 PR 直接提交到该组织下的对应仓库；
• 产品线聚合仓库：每个产品线还有名为$PRODUCTLINE-elements的 meta-repo（如paper-elements、iron-elements、gold-elements），适合提交"元素需求类"Issue，各仓库 README 会维护产品线路线图。

除 GitHub 之外，原文档还列出了一组社区沟通渠道：官方博客、Twitter、Google+ 社区、邮件列表以及 Slack 频道，用于讨论方向性问题和寻求帮助。

这一"分层仓库"结构对 Beaker 的参考价值在于：当你在 Beaker 中发现某个 UI 组件行为异常，应当先判断问题出在组件自身的 Beaker 封装层（例如 app/userland/app-stdlib/js/com/ 下的toast.js、hover-card.js），还是 vendor 的 lit-element 核心层，从而决定在哪个层面修复或上报。

三、签署 CLA：开源贡献的第一道门槛

Polymer 项目使用与所有 Google 开源项目相同的 Contributor License Agreement（贡献者许可协议），其要点包括：

1. 一次性签署：同一份 CLA 适用于所有 Google 开源项目，签署一次即可；
2. 自动标记：签署完成后，后续所有 PR 会自动获得cla: yes标签；
3. 常见问题排查：如果已签署但 CLA-bot 仍然提示未签署，通常是 GitHub 用户名未关联，或 git 提交使用的邮箱与 CLA 记录不一致。此时应核对 CLA 登记信息，并检查本地 git 的user.email配置是否与签署时一致。

四、提交 Bug 的正确姿势：模板、复现与最小示例

原文档对 Bug 提交流程有明确纪律，这些细节对可维护性至关重要：

• 提交位置：核心库问题提交到 Polymer 主仓库；不确定问题时，倾向先提交到元素仓库，由维护者视情况转移；
• 使用模板：尽量按 Issue 模板填写全部字段；
• 附上可复现示例：带复现的 Issue 会被优先处理。原文档推荐使用 jsBin、Plunkr、jsFiddle 或 glitch.me 制作最小复现；针对 lit-element 场景，可以直接基于 StackBlitz 的 lit-element 示例工程改造；若复现必须运行在 IE11，则需要 glitch 上托管源码并通过 polyserve 自动转译的版本（注意 glitch 编辑环境本身不兼容 IE11，但"live"运行链接可用）；
• 关于关闭的 Issue：过时或过于模糊的 Issue 会被关闭，如果问题仍然存在，欢迎重新打开。

五、Pull Request 工作流：从 Issue 到合入的完整链路

原文档给出了一套完整的 PR 贡献步骤，任何贡献者都应按序执行：

1. 先开 Issue：描述要解决的问题与解决思路（若无现成 Issue），便于在代码之外先讨论方案；
2. 签署 CLA：按上文流程完成签署；
3. Fork 仓库：将待修复的仓库 fork 到自己的 GitHub 账号；
4. 编写代码；
5. 整理提交：理想情况下将提交 squash 为单个 commit，并写出清晰的提交信息；确实需要多 commit 时，宁可拆成多个独立 PR；
6. 附带测试：每个 PR 必须包含测试——修 Bug 的 PR，测试必须能捕获该 Bug；加新功能的 PR，新行为必须被完整覆盖（详见下文"单元测试"一节）；
7. 关联 Issue：提交 PR 时引用你创建的 Issue；
8. 给出复现步骤：修 Bug 的 PR，Issue 中要包含清晰的复现步骤，便于维护者验证修复。

完成上述步骤后，核心团队会尽快响应。这套"Issue 先行 + 测试必备"的流程，正是 lit-element 在 Beaker 内部被大量组件安全复用的底层保障。

六、代码规范：元素与核心库的差异化要求

原文档对两类代码贡献给出了不同的规范要求：

• 元素（Elements）代码：Polymer 团队以可工具化、易维护为标准化目标。所有元素应遵循 Polymer 元素风格指南——它定义了属性声明、文档注释的书写方式。遵循该指南的元素可以直接配合iron-component-page元素，把原始元素自动渲染成文档页，实现"代码即文档"；
• 核心库（Polymer library）代码：遵循最常见的 JavaScript/HTML 风格约定（"看代码就知道怎么写"），如需更系统的规范可参考 Google JavaScript 风格指南；
• 安全奖励：Polymer 还参与 Google 的 Patch Rewards 计划，符合条件的安全补丁可获得现金奖励（适用于核心库）。

七、单元测试：polymer-cli 与 lit-element 测试运行指南

原文档用较大篇幅给出了 lit-element 单元测试的完整操作流程，这是整份文档最具实操价值的部分：

7.1 安装测试工具链

所有 Polymer 项目统一使用polymer-cli运行单元测试。为了获得最大灵活性，建议本地全局安装：

npm install -g polymer-cli

7.2 运行 lit-element 单元测试

按以下步骤在本地跑通 lit-element 的测试：

1. 克隆 lit-element 上游仓库；
2. 安装依赖：

npm install

3. 运行测试：

npm test

如果本地已安装polymer-cli，也可以直接：

polymer test --npm

7.3 运行单个测试套件

支持传入测试套件路径来精确运行某个用例集：

npm test <path/to/suite>

或使用 polymer-cli 版本：

polymer test --npm <path/to/suite>

例如：

polymer test --npm test/index.html

7.4 在浏览器中运行测试

先启动本地静态服务：

polymer serve --npm

然后浏览器访问（测试页面由本地方向@polymer/lit-element提供）：

http://localhost:8080/components/@polymer/lit-element/test/index.html

7.5 配置 web-component-tester

默认情况下polymer test会在本机所有已安装浏览器上运行测试。通过web-component-tester（polymer-cli 内部使用的测试运行器）的配置，可以：

• 只在本机可用浏览器的子集上运行；
• 借助 Sauce Labs 在远程浏览器云上运行。

配置方法详见web-component-tester的官方 README，核心思路是在项目的wct.conf.json或package.json的wct字段中声明browsers白名单与sauce凭据。

八、本地查看源码文档

修改源码注释后，可以在本地实时预览生成的文档，步骤如下（每次改动后需重跑第 1 步）：

1. 生成分析数据：

polymer analyze > analysis.json

2. 启动本地服务：

polymer serve

3. 打开http://127.0.0.1:PORT/components/polymer/查看组件文档。

注意：原文档中提到的docs目录与docs/README.md属于上游 lit-element 仓库内容，未随 Beaker 一起 vendor，因此在当前仓库内无法直接打开；如需阅读本地可用的项目资料，可参考 app/userland/app-stdlib/vendor/lit-element/README.md。

九、Beaker 内的落地形态：源码级佐证

以上工作流所保障的 lit-element 能力，在 Beaker 前端代码中得到了充分体现。从源码结构看，Beaker 的 UI 组件体系完全建立在 lit-element 之上：

9.1 组件定义示例

app/userland/app-stdlib/js/com/toast.js 定义了BeakerToast，是典型的 lit-element 用法：

class BeakerToast extends LitElement { constructor ({message, type, button}) { super() this.message = message this.type = type this.button = button } render () { const onButtonClick = this.button ? (e) => { destroy(); this.button.click(e) } : undefined return html` <div id="toast-wrapper" class="toast-wrapper ${this.button ? '' : 'nomouse'}"> <p class="toast ${this.type}">${this.message} ${this.button ? html`<a class="toast-btn" @click=${onButtonClick}>${this.button.label}</a>` : ''}</p> </div> ` } } BeakerToast.styles = toastCSS customElements.define('beaker-toast', BeakerToast)

这里可以看到原文档 README 中描述的三要素全部落地：继承LitElement、实现render()返回 lit-html 模板、通过static styles声明样式并配合customElements.define注册自定义元素。

9.2 响应式属性与样式继承

app/userland/app-stdlib/js/com/hover-card.js 展示了static get properties()（声明响应式属性，此处isHovered: {type: Boolean}）与static get styles()（组件级样式，使用:host选择器与 CSS 变量）的经典组合：

static get properties () { return { isHovered: {type: Boolean} } } static get styles () { return css` :host { position: relative; } ... ` }

9.3 样式即模块：css 标签的规模化使用

Beaker 将组件样式全部封装为 JS 模块，例如 app/userland/app-stdlib/css/buttons.css.js、colors.css.js、common.css.js、inputs.css.js等都以import {css} from '../vendor/lit-element/lit-element.js'开头，把基础样式、颜色变量（var(--blue)、var(--text-color--default)）作为可组合的css模板导出。这正是 lit-element 的css-tag能力——样式会在首次渲染时被finalize并尽可能通过构造的CSSStyleSheet（adoptedStyleSheets）注入，详见 lit-element.js 中的finalize/_getUniqueStyles实现。

9.4 底层属性转换机制

app/userland/app-stdlib/vendor/lit-element/lib/updating-element.js 中的defaultConverter定义了属性与特性的双向转换规则：Boolean类型特性存在即为true；Number从特性解析为数字；Object/Array类型使用JSON.stringify/JSON.parse序列化。同文件 L56-L62 给出了属性声明的默认值（attribute: true、type: String、reflect: false等）。理解这套机制，有助于在 Beaker 组件里正确选择属性类型，避免出现特性与属性值不一致的坑。

十、总结

以 CONTRIBUTING.md 为线索，本文完整还原了 lit-element 上游的贡献流程：渠道定位、CLA 签署、Bug 提交流程、PR 工作流、代码规范，以及基于polymer-cli/web-component-tester的单元测试与本地文档预览方案；同时结合 Beaker 仓库内的toast.js、hover-card.js、*.css.js与updating-element.js源码，展示了 lit-element 在真实产品中的落地用法。无论你是想为上游库贡献力量，还是想在 Beaker 内继续开发基于 lit-element 的组件，都可以把这份文档当作最直接的实操起点。

• 前端