p5.js 发布流程全解析从 semver 标签到 GitHub Release、NPM、官网与 CDN 的自动化流水线【免费下载链接】p5.jsp5.js is a client-side JS platform that empowers artists, designers, students, and anyone to learn to code and express themselves creatively on the web. It is based on the core principles of Processing. Looking for p5.js 2.0? http://beta.p5js.org项目地址: https://gitcode.com/GitHub_Trending/p5/p5.js本文是 p5.js 开源仓库贡献者文档 contributor_docs/release_process.md 的深度解读与实战指南。作为维护者或贡献者你只需在本地执行四条 git/npm 命令即可借助 GitHub Actions 完成从版本号提升、测试、构建到 GitHub Release、NPM 发布、官网数据同步与 CDN 分发的完整发布链路。读完本文你将掌握 p5.js 官方发布机制的整体设计、每一步在 CI 中的具体实现、安全令牌的配置方法以及如何在本地用 act 演练发布流程。总体思路一切自动化一切在 CI 中完成p5.js 的发布流程遵循一个核心设计原则把尽可能多的发布步骤集中到一个地方——GitHub Actions CI 环境。维护者在本地只做最少、最不容易出错的操作切分支、打版本号、推送其余所有环节——运行测试、构建产物、创建 GitHub Release、发布到 NPM、更新官网仓库、同步 Bower 仓库——全部由 CI 工作流在云端完成。原文档还明确了一条架构约定If a new step that is only run on release is required, it should probably be defined in the CI workflow and not as part of the build configuration.——即任何只在发布时执行的新步骤都应该定义在 CI 工作流中而不是塞进构建配置里。这保证了日常构建与发布构建的职责边界清晰也便于维护者集中审查发布行为。版本号策略遵循 SemVer发布流程以 SemVer语义化版本 为版本管理规范版本号格式为MAJOR:MINOR:PATCH文档原文写作MAJOR:MINOR:PATCH即常见的MAJOR.MINOR.PATCHMAJOR主版本号存在不兼容的 API 变更时递增如 p5.js 2.x 相对 1.x 的升级MINOR次版本号以向后兼容的方式新增功能时递增PATCH修订号向后兼容的缺陷修复时递增。在当前仓库中package.json的version字段为2.3.1而.github/workflows/release-workflow-v1.yml与.github/workflows/release-workflow-v2.yml分别监听v1.*.*与v2.*.*两种标签模式这也印证了 p5.js 采用语义化版本并同时维护 1.x 与 2.x 发布通道的现状。发布前置条件在触发一次正式发布之前需要确认以下条件全部满足条件说明Git、Node.js 与 NPM发布脚本在本地需要 Git 与 NPMCI 环境则需要 Node.js当前 v1/v2 工作流均固定使用 Node 22见actions/setup-node步骤构建与推送权限你能够构建库文件且对远程仓库processing/p5.js拥有 push 权限SecretNPM_TOKEN用于向 NPM 发布必须预先配置在远程仓库的 Secrets 中SecretACCESS_TOKEN用于代表 CI 向p5.js、p5.js-website、p5.js-release等关联仓库写入必须预先配置安全令牌两个必须预先设置的仓库 Secret发布工作流需要两个 GitHub 仓库级加密 Secretrepository secrets缺一不可。这两个令牌的职责有严格区分NPM_TOKEN负责发布到 NPM按 NPM 官方文档 创建具备read and publish权限的令牌令牌所属的 NPM 账号必须对p5这个包拥有发布权限在 CI 中该令牌被注入到发布步骤JS-DevTools/npm-publishaction的token参数中。从源码看v1 与 v2 工作流都在env层声明了INPUT_TOKEN: ${{ secrets.NPM_TOKEN }}并在 NPM 发布步骤中显式使用。ACCESS_TOKEN负责跨仓库写入这是一个personal access tokenPAT属于一个对p5.js、p5.js-website、p5.js-release三个仓库都有访问权限的账号生成时参考 GitHub PAT 创建指南Scope 只勾选repo和workflow两项不要多给官方强烈建议使用组织专用账号而非个人账号并将该账号的写权限严格限制在所需的三个仓库上以降低令牌泄露时的爆炸半径。在 CI 中ACCESS_TOKEN用于actions/checkout克隆processing/p5.js-website与processing/p5.js-release仓库以及ad-m/github-push-action将更新后的内容推送回对应仓库。发布操作本地只需四步整个发布动作在本地浓缩为四条命令在仓库根目录执行$ git checkout main $ npm version [major|minor|patch] # Choose the appropriate version tag $ git push origin main $ git push origin v1.4.2 # Replace the version number with the one just created above各命令的作用与注意点git checkout main先切到主干分支确保发布基于最新主干代码npm version [major|minor|patch]根据变更类型选择major、minor或patch。该命令会同步完成三件事——更新package.json的version字段、生成对应的 git tag例如v1.4.2、创建一次版本提交git push origin main推送主干分支使package.json中的新版本号进入远端git push origin vX.Y.Z推送刚创建的版本标签。注意推送标签这一步是触发 CI 发布工作流的开关——工作流的触发条件on: push: tags正是匹配这个标签。执行完毕后真正的发布步骤全部在 GitHub Actions CI 上运行本地无需再做任何操作。监控与结果核验在 Actions 页面跟踪进度推送标签后打开 p5.js 仓库的Actions标签页寻找名为New p5.js releasev1 工作流或New p5.js 2.x releasev2 工作流的 job点击进入即可查看详细的运行日志包括测试输出、构建产物、GitHub Release 创建与 NPM 发布结果。逐渠道核验结果发布 job 完成后需要按以下顺序核验各发布渠道GitHub Release在 Releases 页面会看到一个draft草稿状态的新版本——这是softprops/action-gh-release以draft: true创建的结果。维护者应打开草稿必要时修订自动生成的 changelog然后手动点击 Publish 正式发布NPM在 NPM 的p5包页面确认最新版本号已出现官网p5.js 官网的更新由其自身的构建与部署 job 完成可在p5.js-website仓库的 Actions 页面监控完成后在官网 Downloads 页面核对最新版本号CDNCDN 会自动从 NPM 拉取新版本通常需要一两天的延迟无需任何人工操作。幕后机制CI 工作流到底做了什么原文档提到触发工作流的是.github/workflows/release.yml而在当前仓库中实际落地为两份按主版本区分的文件.github/workflows/release-workflow-v1.yml监听v1.*.*与v1.*.*-*标签负责 1.x 版本线.github/workflows/release-workflow-v2.yml监听v2.*.*与v2.*.*-*标签负责 2.x 版本线并额外增加 TypeScript 类型生成与校验步骤。另外仓库根目录的 .github/release.yml 是 GitHub 自动生成 Release Notes 的配置默认排除Dependencies标签与dependabot账号的提交并将变更分类为 Whats Changed 与 New Contributors 两个板块后者收录allcontributors账号的贡献者条目。触发条件与预发布判断工作流由push到匹配v*.*.*模式的标签触发同时兼容v*.*.*-*形式的预发布标签。触发后首先进行预发布判断- name: Check prerelease id: semver run: | if [[ ${{ github.ref_name }} *-rc* ]]; then echo is-prereleasetrue $GITHUB_OUTPUT else echo is-prereleasefalse $GITHUB_OUTPUT fi如果标签名包含-rc后缀则判定为预发布is-prereleasetrue。这一判断会向下游传递两个关键影响GitHub Release 会以prerelease: true创建v1 与 v2 工作流均是如此涉及外部仓库写入的步骤NPM 发布、官网更新、Bower 同步会通过if: ${{ steps.semver.outputs.is-prerelease ! true }}全部跳过避免预发布版本污染正式渠道。五大步骤的源码级还原综合 v1/v2 两份工作流触发后的完整执行序列如下步骤 1环境准备与质量门禁actions/checkout克隆仓库注意设置persist-credentials: false避免将凭据带入后续步骤actions/setup-node配置 Node.jsv1/v2 均固定为 Node 22v1 注释明确说明Keep at 22 purposefully for v1从标签提取版本号version$(echo ${{ github.ref_name }} | cut -c 2-)即去掉标签首字母v记录当前日期用于版本横幅npm ci安装依赖CI 模式npm test运行测试——这是发布前的质量门禁测试失败则流程中止。v2 工作流运行npm test -- --projectunit-tests并在npm run build后追加npm run generate-types生成types/下的 TypeScript 声明与npm run test:types校验类型确保 2.x 发布的类型文件正确npm run build执行构建。从 package.json 可见构建脚本为rolldown -c对应 rolldown.config.js产物包含lib/p5.jsIIFE 格式带版本横幅/*! p5.js vX.Y.Z ... */、lib/p5.min.js、lib/p5.esm.js、lib/p5.esm.min.js以及lib/p5.webgpu*.js等 WebGPU 附加模块和dist/目录的 ESM 源码构建。版本号通过replacePlugin中的VERSION_WILL_BE_REPLACED_BY_BUILD: pkg.version注入到源码中横幅日期则通过new Intl.DateTimeFormat(en-US, ...)生成。步骤 2打包发布文件- run: mkdir release mkdir p5 cp -r ./lib/* p5/ - name: Create release zip file uses: TheDoctor0/zip-release... with: type: zip filename: release/p5.zip path: ./p5/* - name: Copy release files run: cp lib/p5.js lib/p5.min.js lib/addons/p5.sound.js lib/addons/p5.sound.min.js release/先将lib/下所有产物复制到p5/目录打包成release/p5.zip作为压缩包附件再把核心分发文件v1 为p5.js、p5.min.js及p5.sound.js两个 addonsv2 为p5.js、p5.min.js、p5.esm.js单独复制到release/目录作为 GitHub Release 的独立附件。步骤 3创建 GitHub Release 并发布 NPM使用softprops/action-gh-release创建draft草稿Releasedraft: true、prerelease由步骤 1 的预发布判断决定、generate_release_notes: true让 GitHub 依据 .github/release.yml 自动生成 Release Notes、附件为release/*使用JS-DevTools/npm-publish发布到 NPM。v1 工作流中此步骤带if: is-prerelease ! true条件v2 工作流则始终执行但通过tag: latest|beta区分正式版与 beta 通道——正式版走latest预发布版走beta。步骤 4更新 p5.js 官网仓库用ACCESS_TOKEN通过actions/checkout克隆processing/p5.js-websitev1 推送到v1分支v2 推送到main分支fetch-depth: 0保证完整历史npm install后依次执行官网自身的构建脚本build:p5-version、build:contributor-docs、build:contributors、build:reference、build:search以github-actions[bot]身份提交commit message 为Update p5.js to ${{ github.ref_name }}用ad-m/github-push-action配合ACCESS_TOKEN推送回官网仓库。原文档中提到的复制data.json、data.min.json、p5.min.js、p5.sound.min.js、更新data.yml与en.json等操作在当前实现中已整合进官网仓库的build:p5-version等构建脚本——参考文档数据生成逻辑可参见 utils/convert.mjs它读取docs/data.json并输出docs/reference/data.json与docs/reference/data.min.json以及用于参数校验的docs/parameterData.json这些数据文件即官网参考文档的数据来源。步骤 5同步 Bower 发布仓库用ACCESS_TOKEN克隆processing/p5.js-releaseBower 发布仓库到bower/目录复制库文件cp lib/*.js bower/lib/与cp lib/addons/* bower/lib/addons/以 bot 身份提交并推送到master分支该仓库默认分支为master。本地测试发布流程用 act 模拟 CI由于发布步骤全部运行在 CI 中本地测试并不直观。官方推荐使用 act 在本地模拟 GitHub Actions 的执行——发布工作流开发期间正是用这种方式测试的。不过有两个注意事项测试步骤可能不会完整运行完整测试需要 mocha/Chrome 浏览器测试环境所依赖的系统组件本地往往缺失。通常需要先用apt安装若干系统依赖再配置其余环境。建议紧盯错误信息它会明确提示缺少哪些包必须注释掉涉及远程推送的步骤工作流中的克隆并推送p5.js-website/p5.js-release等步骤会真实改动远端仓库本地演练前务必注释掉以免意外推送未经验证的改动。由于 act 的具体操作步骤会随工作流定义演进而变化官方文档仅给出上述方向性说明精确步骤建议以当时的工作流文件与 act 文档为准。关键要点回顾触发即发布git push origin vX.Y.Z是唯一开关其余全部交给 CI质量门禁前置npm testv2 还包含类型生成与校验不通过则不会产生任何发布产物草稿机制GitHub Release 以 draft 创建changelog 可人工修订后再正式发布预发布隔离-rc标签走 prerelease 通道且跳过 NPM 正式版、官网与 Bower 的更新双令牌隔离NPM_TOKEN只管 NPM 发布ACCESS_TOKEN只管跨仓库写入权限最小化外部仓库写入集中在 CI官网p5.js-website与 Bowerp5.js-release的更新均由工作流内的专用步骤完成不在本地执行。【免费下载链接】p5.jsp5.js is a client-side JS platform that empowers artists, designers, students, and anyone to learn to code and express themselves creatively on the web. It is based on the core principles of Processing. Looking for p5.js 2.0? http://beta.p5js.org项目地址: https://gitcode.com/GitHub_Trending/p5/p5.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考