webgems 贡献指南：从 Issue 反馈、PR 提交流程到资源条目 JSON Schema 全解析-北京尧图网络

开发工具【免费下载链接】webgemsA curated list of resources for devs and designers. Join me on devcord.com if you are up for a chit chat :)项目地址https://gitcode.com/gh_mirrors/we/webgems点击查看免费下载webgems.io 是一个面向开发者与设计师的精选资源导航站curated list以 Vue.js Nuxt 构建所有资源数据以 JSON 形式存放在仓库的resources/目录中。本文以仓库根目录的 CONTRIBUTING.md 为骨架结合 package.json、resources/、utils/pure.js、test/pure.test.js 等源码与测试完整讲解 webgems 的贡献规范如何报告 Issue、如何按规范提交 Pull Request、如何用wgem代码片段快速生成资源条目模板以及新增分类时如何接入 Nuxt 的路由生成机制。读完本文你将能独立完成一次符合项目规范的资源提交或代码贡献。一、贡献前必须了解的三件事1. 贡献不一定都会被采纳先对齐项目愿景webgems 项目明确表示贡献者提交的 bug 报告、功能请求或新资源维护者会尽力整合但并非所有贡献都会与项目愿景一致部分 Issue 或 PR 可能被拒绝。因此 CONTRIBUTING.md 给出的黄金建议是动手实现之前先开一个 Issue 与维护者讨论你的想法。这一步能避免大量返工也让维护者有机会提前给出反馈或调整方向。2. 遵守社区行为准则所有与项目维护者及社区的互动都必须遵循 CODE_OF_CONDUCT.md。该准则基于 Contributor Covenant 1.4 改编核心要求包括使用欢迎与包容的语言、尊重不同观点、礼貌接受建设性批评、杜绝骚扰与攻击性言论等。违规行为可被举报至abusewebgems.io由项目团队调查处理。3. 用 Issue 而非直接修改来验证想法如果你不确定改动是否符合项目方向文档推荐先提交 Issue 讨论再开始编码——这是整个贡献流程的第一步也是后续 PR 能否顺利合并的前提。二、Issue报告 bug 与功能建议当你想报告 bug 或建议增强时可以直接在该仓库中打开一个 Issue。要点如下使用仓库提供的 Issue 模板模板覆盖了维护者最关心的常见问题能帮助维护者更快理解你的反馈。提交前先搜索查重使用项目的 issue 搜索功能快速检查避免提交重复 Issue。如果相同反馈已存在可以在该 Issue 上添加 1表情回应或在评论中补充更多细节而不是新建一条。类型不限bug 报告、增强建议、新资源推荐均被欢迎。三、Pull Request完整的代码贡献流程CONTRIBUTING.md 将 PR 流程拆分为 7 个步骤下面结合仓库源码逐一展开。第 0 步确保你的改动会被接受如第一部分所述建议先开 Issue 讨论你的改动方向确认后再进入编码阶段。第 1 步Fork 并基于dev分支新建功能分支Fork 并 clone 项目后基于项目的dev分支而非master创建新的功能分支。这一点在后续开 PR 时也必须保持因为 PR 的 base 分支默认要指向dev。第 2 步安装依赖在项目根目录执行npm install从 package.json 可以看到项目运行在 Nuxt 2nuxt: ^2.14.6之上依赖还包括vue-i18n、ramda函数式工具库用于数据查询、nuxt-clipboard2剪贴板复制等。开发依赖中包含pug/pug-plain-loader、node-sass/sass-loader、tailwindcss、jest、eslint等对应项目使用的 Pug 模板、SCSS 样式与测试体系。第 3 步用 npm scripts 完成日常开发任务package.json 中的scripts字段与文档描述的开发命令一一对应npm 脚本实际命令作用npm run devnuxt启动开发服务器默认监听localhost:3000支持热重载npm run buildnuxt build构建生产版本应用npm startnuxt start启动生产服务器需先buildnpm run generatenuxt generate生成站点最终预渲染pre-rendered静态版本npm run linteslint --ext .js,.vue --ignore-path .gitignore .检查 JS/Vue 代码风格npm run lintfixeslint --fix --ext .js,.vue --ignore-path .gitignore .自动修复代码风格问题npm run testjest运行 Jest 单元测试见下文测试章节文档特别指出npm run build; npm start组合可用来构建并本地预览生产版npm run generate则用于生成最终静态站。这与 nuxt.config.js 中的generate.routes配置相呼应——该配置会读取resources/下所有分类的slug作为动态路由因此在generate阶段每个分类页都会被预渲染为静态 HTMLgenerate: { routes: resources.map(category category.slug), },第 4 步开始编码具体编码内容请参考下一节“资源条目提交”或按项目技术栈Vue.js Nuxt查阅其官方文档。项目页面组件位于 pages/例如分类页 pages/_category.vue 通过$store.getters[data/sortByTitle]获取排序后的分类资源卡片渲染由 components/Card.vue 完成。第 5 步提交并推送打开 PR将改动提交并推送到你的 fork然后在 GitHub UI 中新建 Pull Request。base 分支必须设为dev而不是master如果漏设之后也可以通过 PR 标题旁的 Edit 按钮修正。排除构建或安装产物例如yarn.lock、日志文件等不要将其包含进 changeset。第 6 步等待评审维护者通常需要**至少两个 approving review批准评审**才会合并 PR。合并前如果你愿意可以把名字加到 CONTRIBUTORS.md 文件中。如果被要求追加修改直接在原 PR 对应的分支上新增 commit 并推送即可无需重新开 PR。四、添加一个新资源条目JSON Schema 详解这是 webgems 贡献中最常见的场景也是 CONTRIBUTING.md 中给出完整模板的核心章节。1. 使用 VS Code 代码片段快速生成模板如果你使用 VS Code在resources文件夹的任意 JSON 文件中输入wgem并按 Tab 键即可展开正确的模板骨架。2. 完整的 JSON Schema对于其他编辑器请使用以下 schema[ { title: String, // Start with uppercase slug: String, // All lowercase, eg: /category resources: [ { title: String, desc: String, // 1 - 2 sentences long url: String, // See below for notes about correct format of URLs tags: [String] // Please try to add at least 3 single-worded tags } ] } ]字段规范要点title分类名首字母大写Start with uppercase。slug全小写形如/category用于生成路由。resources[].title资源名称。resources[].desc12 句话的描述。resources[].url资源链接格式要求见下文。resources[].tags标签数组至少添加 3 个单词型标签single-worded tags便于站内标签检索。3. URL 的三大书写规范文档对 URL 格式有明确约束违反会导致 PR 被拒不要链接到语言专属页面例如不要写url.org/en-US/docs应尽量写url/docs。这保证资源对所有语言的访问者一致可用。不要使用字符会破坏 URL 引用可能被解析为 HTML 实体或查询参数分隔符。不接受 referral links返利/引流链接。4. 实际文件示例仓库的 resources/ 目录中每个分类对应一个category.json文件。以 resources/css.json 为例其结构完全遵循上述 schema{ title: CSS, slug: /css, resources: [ { title: CSS Grid Generator, desc: Visually create your css grid and export the code., url: https://cssgrid-generator.netlify.com/, tags: [generator, grid, layout, visual tool] }, { title: Flexbox Froggy, desc: A game to learn Flexbox, url: https://flexboxfroggy.com, tags: [educational, beginner, interactive] } ] }你只需把建议的资源追加到对应分类 JSON 文件的resources数组中并包含全部四个字段title、desc、url、tags不要遗漏。五、添加一个全新分类接入 Nuxt 路由当现有分类都无法容纳你的资源时可以新增一个分类流程如下新建category.json文件放在 resources/ 目录中内容遵循前述 schema。在 resources/index.js 中注册先import该文件再加入导出数组。该文件目前导出了 18 个分类CSS、Design、HTML、JavaScript、PHP、Python、Ruby、Rust、Server、Utility、Icons、Accessibility、Podcasts、Daily、Frontend、Fullstack、General、Content Creators并在导出前按title字母序排序import css from ./css import daily from ./daily // ... 其余分类 const sortByTitle ({ title: titleA }, { title: titleB }) { if(titleA titleB) return -1 if(titleA titleB) return 1 return 0 } export default [ css, daily, /* ... */ ].sort(sortByTitle)注册完成后Nuxt 便能自动为这个新分类生成并渲染对应页面动态路由由generate.routes依据slug自动收集分类页模板见 pages/_category.vue。六、从源码看资源数据如何被消费与校验理解数据“落地”后的处理链路能帮你写出格式完全正确的条目。1. 数据转换transformToResourcesstore/data.js 在 Vuex state 初始化时调用transformToResources(categories)处理全部原始分类数据其实现位于 utils/pure.jsconst addCleanTitleAndPath R.curry((slug, obj) { const cleanTitle cleanStringAndRemoveSpaces(obj.title) return { ...obj, cleanTitle, path: ${slug}?card${cleanTitle}, } })即每个资源会被追加两个派生字段cleanTitle标题去掉空格并转为小写cleanStringAndRemoveSpaces R.compose(R.replace(/ /g, ), R.toLower, R.trim)用于排序与高亮定位path形如/css?cardcssgridgenerator用于复制分享链接与路由跳转pages/_category.vue 通过$route.query.card定位高亮卡片。这一行为在测试 test/pure.test.js 中有直接验证输入 test/mockCategories.json 中的原始数据输出 test/mockOutput.json 中的增强数据例如CSS Grid Generator变为cleanTitle: cssgridgenerator、path: /css?cardcssgridgenerator。提交资源后运行npm run test即可回归验证。2. 标签与搜索如何依赖tags字段store/data.js 中的findByTagsgetter 会基于资源tags数组做检索getAllTagsutils/pure.js则会聚合全站去重标签用于侧边栏展示。这就是文档要求“至少 3 个标签”的原因——标签过少会削弱站内搜索与分类体验。3. 卡片渲染对字段的依赖components/Card.vue 渲染每条资源时使用resource.url标题链接、favicon 来源、打开按钮、resource.desc描述文本。因此四个字段缺一不可缺失会导致卡片显示不完整。七、技术栈说明webgems.io 使用Vue.js与Nuxt构建相关证据遍布仓库nuxt.config.js 配置了 head 元信息、generate路由、ESLint 热重载与nuxt-clipboard2模块页面模板使用 Pugtemplate langpug样式使用 SCSSstore/ 采用 Vuex 组织数据data模块负责资源查询Sidebar模块负责视图切换utils/pure.js 用 Ramda 以函数式风格实现纯函数便于单元测试。想深入理解 Vue/Nuxt 机制时可参考其各自的官方文档再对照本仓库源码实践。总结一份高质量贡献的检查清单参照 CONTRIBUTING.md 与仓库源码一次合格的贡献应满足先讨论不确定方向时先开 Issue与维护者对齐愿景分支与依赖基于dev分支创建功能分支根目录执行npm install本地验证用npm run dev开发调试用npm run lint/npm run test通过风格检查与单元测试资源条目规范字段完整title/desc/url/tagstags至少 3 个单词型标签URL 无语言专属页、无、无 referral 链接新分类记得在 resources/index.js 注册PR 规范base 分支设为dev剔除yarn.lock等构建/安装产物等待至少两个 approving review可选加分合并前把自己加入 CONTRIBUTORS.md。遵循上述流程你的 Issue 与 PR 就能以最高效率被维护者审阅并合并到 webgems 的资源库中。赞分享开发工具【免费下载链接】webgemsA curated list of resources for devs and designers. Join me on devcord.com if you are up for a chit chat :)项目地址https://gitcode.com/gh_mirrors/we/webgems点击查看免费下载相关推荐Visdom源码贡献指南从Issue提交到PR流程Visdom源码贡献指南从Issue提交到PR流程引言为什么贡献Visdom Visdom作为Facebook开源的交互式可视化工具为PyTorch等数据可视化前端揭秘Open-LLM-VTuber如何用开源技术打造你的专属AI虚拟伴侣揭秘Open LLM VTuber如何用开源技术打造你的专属AI虚拟伴侣你是否想过让一个能听会说的虚拟角色成为你的编程伙伴、学习助手或创意灵感来源在人工AI 应用大模型语音数字人交互助手本地部署cwc-workshops provided.py 深度解读System Prompt、工具Schema与聊天UI 三大复用模式cwc workshops provided.py 深度解读System Prompt、工具Schema与聊天UI 三大复用模式在 cwc workshop示例工程上一篇CANN ops-sparse核心API详解从零掌握稀疏矩阵向量乘法SpMV的10个关键技巧下一篇如何5分钟快速搭建EasyImages2.0图床从安装到上线的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

webgems 贡献指南：从 Issue 反馈、PR 提交流程到资源条目 JSON Schema 全解析

相关推荐

LAMMPS `dihedral_style cosine/squared/restricted` 完全指南：MARTINI 力场受限余弦二面角势的实现与使用

大促前端断网保活底座：利用 Service Worker 拦截器实现静态资产的零失败率

HoloCubic 固件中的 lvgl Switch 开关组件实战：基于 lv_ex_switch 示例的创建、事件与样式解析

更多资讯

APQP平台化引擎：汽车电子研发管理如何告别流程灰区

华为题：编辑距离

螺旋矩阵II：用循环不变量与左闭右开区间搞定边界

Spring Boot宠物医院管理系统：从数据库设计到部署实战解析

从曲面细分到计算着色器：我的 Vulkan 实验记录

自由出入宇宙空间：是工程学奖励还是本体论属性？

今日更新

防关联浏览器哪个好？三款产品实测差异解析

2026钢铁行业AI转型系统选型对比：多基地排产、大宗原燃料采购与质量追溯，六家厂商能力差异在哪里

影刀RPA深度实战：大模型Fine-tuning定制RPA专用Prompt与指令生成

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？