Release Process

Release Process

This repo ships pdfjs-dist-style artifacts from build/dist/. There are two CI paths plus a manual path. Default package name may be scoped (e.g., @okkkde/pdfjs-dist); npm publishes use --access public.

Version source

• Build version is taken from PDFJS_VERSION env; if absent, the legacy counter (versionPrefix + commit count) is used.
• Dist artifacts place the version into build/version.json and build/dist/package.json.

Secrets

• NPM_TOKEN: npm automation token with publish rights.
• GITHUB_TOKEN: provided by GitHub for tagging/releases (already available).

Workflows

1) Sync Upstream (.github/workflows/sync_upstream.yml)

• Trigger: cron (03:00 UTC) or manual workflow_dispatch.
• Flow:
  1. Fetch upstream tags; pick the latest upstream tag (by commit date).
  2. If that tag’s commit is not yet in master, merge the tag into master (retains fork changes) and push master.
  3. Set PDFJS_VERSION to the upstream tag (strip leading v).
  4. npm ci → npx gulp dist → npm publish ./build/dist --access public.
  5. Tag master with the same upstream tag and push the tag.
  6. Create a GitHub Release for that tag.
• Safeguard: If the tag’s commit is already reachable from master, the workflow exits without publishing.

2) Auto Release (.github/workflows/auto_release.yml)

• Trigger: push tags matching v*; manual workflow_dispatch also allowed.
• Guard: Skips if the actor is github-actions[bot] (to avoid double-publish after sync_upstream).
• Flow for tag pushes:
  1. Set PDFJS_VERSION=${GITHUB_REF_NAME#v}.
  2. npm ci → npx gulp dist → npm publish ./build/dist --access public.
  3. Create GitHub Release (uploads tar/zip artifacts).
• For manual dispatch, provide PDFJS_VERSION yourself (via input or env) if you want a specific version.

Local / manual release

• Choose a version: set PDFJS_VERSION=0.0.x (supports suffixes like -beta1).
• Build and publish:

  npm ci
  PDFJS_VERSION=0.0.x npx gulp dist
  npm publish ./build/dist --access public --tag next

• The dist layout contains both .mjs and .js twins for ESM bundles.

Notes

• Upstream repo has no root version field; tags define official versions. We mirror upstream tags and reuse them as PDFJS_VERSION.
• If you change the package name (scoped), keep --access public to avoid 402 errors for private scopes.
• Avoid tag storms: auto_release is skipped when tags come from sync_upstream to prevent double publishes.

发布流程

本仓库发布的 npm 包来自 build/dist/，保持与官方 pdfjs-dist 结构一致（含 .mjs 及对应的 .js 双份模块）。默认包名可用 scoped（如 @okkkde/pdfjs-dist），发布统一加 --access public。

版本来源

• 构建版本号优先取环境变量 PDFJS_VERSION；若未设置，则退回旧逻辑（pdfjs.config 的前缀 + 自基准提交的计数）。
• 构建时将版本写入 build/version.json 和 build/dist/package.json。

凭据

• NPM_TOKEN：npm 自动化 token，具备发布权限。
• GITHUB_TOKEN：GitHub 自带，用于推 tag / 建 Release。

工作流

1) 同步上游（.github/workflows/sync_upstream.yml）

• 触发：每日 03:00 UTC 定时或手动 workflow_dispatch。
• 步骤：
  1. 拉取 upstream tag，取最新 tag（按提交时间）。
  2. 若该 tag 对应提交尚未包含在 master，则合并该 tag 到 master（保留 fork 改动），并推送 master。
  3. 设定 PDFJS_VERSION = 上游 tag（去掉前缀 v）。
  4. npm ci → npx gulp dist → npm publish ./build/dist --access public。
  5. 给合并后的 master 打同名 tag 并推送。
  6. 创建 GitHub Release。
• 防抖：如果 tag 已被包含在 master，则直接退出不发布。

2) 自动发布（.github/workflows/auto_release.yml）

• 触发：推送符合 v* 的 tag；可手动 workflow_dispatch。
• Guard：如果触发者是 github-actions[bot]（来自 sync_upstream 的 tag），则跳过以避免重复发布。
• 流程（tag 推送）：
  1. 设置 PDFJS_VERSION=${GITHUB_REF_NAME#v}。
  2. npm ci → npx gulp dist → npm publish ./build/dist --access public。
  3. 创建 GitHub Release（上传 tar/zip）。
• 手动触发时，如需特定版本，请自行设置 PDFJS_VERSION。

本地 / 手动发布

• 设定版本（支持 -beta1 等后缀）：PDFJS_VERSION=0.0.x
• 构建与发布：

  npm ci
  PDFJS_VERSION=0.0.x npx gulp dist
  npm publish ./build/dist --access public --tag next

其他说明

• 上游根目录无 version 字段；官方版本由 tag 决定，fork 会镜像该 tag 并用作 PDFJS_VERSION。
• 若更换包名为 scoped，务必加 --access public，否则 npm 会返回 402。
• 已避免“重复触发”：sync_upstream 推出的 tag 不会再次触发 auto_release 发布。