SuperCollider 发布里程碑贡献者名单生成器：GitHub REST API 数据抓取与统计脚本实战解析

• 音频处理
• 编程语言

导读

package/contributor-list-generator/是 SuperCollider 仓库中一个面向发布流程的小型工具集，用于从 GitHub REST API 抓取指定里程碑（milestone）内关闭的 Issue 与合并的 Pull Request，并据此生成一份按用户聚合的贡献者名单。本文以 README.md 为主线，结合 fetch-data.sh、contributors.js 与 package.json 的源码实现，完整讲解该工具的依赖安装、数据抓取、统计口径与输出格式，并延伸说明它如何与 changelog_to_schelp.sh 等package/目录下的发布辅助脚本协同，帮助维护者在发布新版本时快速生成致谢名单。

工具定位与整体工作流

从仓库结构看，package/目录集中存放与发布打包相关的辅助脚本（如源码 tarball 生成脚本create_source_tarball.sh、changelog 格式转换脚本changelog_to_schelp.sh），而contributor-list-generator/则专门负责「从 GitHub 数据生成贡献者名单」这一环节。

原文档给出的完整操作流程如下：

# 1. 安装 Node 依赖（lodash） npm install # 2. 删除可能残留的旧数据目录 trash github-data/ # 3. 交互式输入里程碑 ID，抓取 GitHub API 数据 ./fetch-data.sh # 4. 汇总统计并打印贡献者名单 node contributors.js

整个流程只有四个步骤：npm install准备运行环境 →trash清理旧数据 →fetch-data.sh抓取原始 JSON →contributors.js聚合输出。其中trash是一个独立的命令行工具（而非 Node 依赖），用于将旧目录移入回收站而非直接删除，运行前需要确保系统已安装该命令；如果本机没有trash，也可等价改用其他方式清空github-data/目录。

第一步：依赖安装与数据目录管理

npm install 与 package.json

package.json 声明了本工具唯一的运行时依赖：

• lodash（^4.16.2，devDependencies）：contributors.js使用其flatten、each、sortBy等工具函数完成数组扁平化、数据聚合与排序；
• 项目本身无测试脚本（test命令仅输出提示后以状态码 1 退出），main字段指向changelog.js，说明该目录历史上与 changelog 处理相关，当前核心脚本为contributors.js。

安装命令：

npm install

执行后会在package/contributor-list-generator/下生成node_modules/与package-lock.json，其中包含 lodash。

清理旧数据目录

trash github-data/

fetch-data.sh会向github-data/目录写入labels.json、issues-closed-{n}.json、pulls-closed-{n}.json等文件；contributors.js启动时会按固定文件名读取这些 JSON。若上次运行留下了残缺或不完整的数据，会导致统计结果混入旧数据，因此文档要求每次运行前先清空该目录。

第二步：fetch-data.sh 抓取 GitHub API 数据

fetch-data.sh 是一个#!/usr/bin/env bash脚本，职责是「针对某个里程碑抓取对应的 issues 与 pull-requests 数据」。它的关键设计点如下。

交互式获取里程碑 ID

脚本并不接受命令行参数，而是通过read交互式提示输入：

mkdir -p github-data echo "Please enter milestone ID number." echo "To find the milestone ID, visit the milestone page in your browser and look at the last part of the URL." read -p "Milestone ID: " milestone

需要说明的是：GitHub 的 API 参数milestone要求的是里程碑的数字 ID，而不是里程碑名称。脚本注释给出了获取方式——打开仓库的 milestones 页面（https://github.com/supercollider/supercollider/milestones），每个里程碑详情页 URL 末尾的数字段即为其 ID。

三个 curl 请求

脚本通过三条curl命令抓取数据：

# 下载全部标签（labels） curl "https://api.github.com/repos/supercollider/supercollider/labels?per_page=100" -o github-data/labels.json # 下载该里程碑下已关闭的全部 issues（前 5 页，每页 100 条） curl "https://api.github.com/repos/supercollider/supercollider/issues?per_page=100&page=[1-5]&state=closed&milestone=$milestone" -o "github-data/issues-closed-#1.json" # 下载该里程碑下已关闭的全部 pull-requests（前 2 页） curl "https://api.github.com/repos/supercollider/supercollider/pulls?per_page=100&page=[1-2]&state=closed&milestone=$milestone" -o "github-data/pulls-closed-#1.json"

这里值得展开的工程细节有三点：

1. curl 的 URL 通配符展开：[1-5]是 curl 原生的数字区间展开语法，-o输出文件名中的#1会被替换为当前展开的页码。因此这组命令实际会生成issues-closed-1.json到issues-closed-5.json（共 5 个文件）以及pulls-closed-1.json、pulls-closed-2.json（共 2 个文件）。
2. 分页策略：每页per_page=100，Issue 请求最多取 5 页（约 500 条），Pull Request 请求最多取 2 页（约 200 条）。这是一个面向单里程碑规模的保守上限——单个里程碑的关闭条目通常远小于此。
3. state=closed与milestone=$milestone过滤：接口层先做粗粒度过滤，只拉取「已关闭且属于该里程碑」的数据，后续的精确过滤（是否合并、是否有效）交给contributors.js处理。

需要注意的是，GitHub 的/issues端点返回的数据中同时包含 Issue 与 Pull Request 两种条目，二者以pull_request字段区分；脚本另行请求/pulls端点正是为了拿到 PR 独有的merged_at（合并时间）字段。

第三步：contributors.js 的统计口径与输出

contributors.js 是纯 Node.js 脚本（CommonJS 风格，使用require），头部注释明确了它的功能定位：

Prints contributors list sorted by number of issues and pull requests. Closed issues and successfully merged pull-requests only.

即：只统计「关闭的 Issue」与「成功合并的 Pull Request」，并生成贡献者名单。其处理流水线可分为四个阶段。

阶段一：加载并扁平化数据

var ib = []; var pb = []; for (var i = 0; i < 10; i++) { var jsonPath = `./github-data/pulls-closed-${i}.json`; if (fs.existsSync(jsonPath)) { var d = require(jsonPath); pb.push(d); } var jsonPath2 = `./github-data/issues-closed-${i}.json`; if (fs.existsSync(jsonPath2)) { var d = require(jsonPath2); ib.push(d); } } var pulls = _.flatten([].concat(pb)); var issues = _.flatten([].concat(ib));

脚本以./github-data/为数据根目录，循环尝试加载pulls-closed-0.json至pulls-closed-9.json、issues-closed-0.json至issues-closed-9.json（共各 10 个文件的探测上限），只加载实际存在的文件，再用_.flatten把多个分页数组合并为单一数组。这里值得注意的是：虽然fetch-data.sh只生成 1～N 的编号文件（从 1 开始），而 JS 从 0 开始探测，由于existsSync会跳过不存在的编号，两类编号风格并不会造成冲突。

阶段二：合并口径过滤（shouldIncludeIssue / shouldIncludePull）

var pullsMap = {}; _.each(pulls, (p) => { pullsMap[p.number] = p; }); function shouldIncludePull(pull) { // has been merged return pull.merged_at && shouldIncludeIssue(pull); } function shouldIncludeIssue(issue) { var status = (issue.state === 'closed'); if (!status) { return false; } // if number is in pulls and there is no merged at var pull = pullsMap[issue.number]; if (pull) { // was never merged if (!pull.merged_at) { return false; } } return true; }

过滤逻辑的核心规则可以归纳为：

• Issue 必须处于closed状态才可能被计入；
• 若该编号同时存在于 pulls 数据中（即它实际上是一条 Pull Request），则必须满足merged_at非空，即该 PR 被成功合并，否则排除；
• shouldIncludePull额外要求merged_at存在，作为对 pulls 数组的独立校验。

由此可以确认最终统计口径：「该里程碑内关闭的有效 Issue」+「该里程碑内成功合并的 PR」。反过来，关闭但未合并的 PR、仍处于 open 状态的条目都会被排除——这正是文档中「closed issues and successfully merged pull-requests only」的实现落地。

阶段三：按用户聚合计数

var issuesData = issues.filter(shouldIncludeIssue).map(mapIssueData); var users = {}; _.each(issuesData, (pull) => { if (users[pull.user.name]) { users[pull.user.name].count += 1; } else { pull.user.count = 1; users[pull.user.name] = pull.user; } });

mapIssueData从每条通过过滤的条目中只提取user.login与user.html_url两个字段；随后以登录名为 key 聚合成users字典，每个用户累计count（其关闭/合并的条目总数）。

阶段四：排序与输出

users = Object.keys(users); users = _.sortBy(users, (user) => user.toLowerCase()); console.log(users.join(", "));

最终输出是一行以逗号+空格分隔的登录名列表，排序规则为按登录名的小写形式进行字母序排序（sortBy(users, u => u.toLowerCase())），保证大小写混合的 GitHub 用户名也能获得稳定一致、对大小写不敏感的顺序。这行纯文本输出可以直接复制到发布公告、致谢名单或 changelog 中使用。

源码注释与文档的细微出入

从源码结构看，可以指出一个值得读者注意的细节：脚本头注释写的是 "sorted by number of issues and pull requests"，但实际输出（console.log(users.join(", "))）只打印用户名列表，并未直接输出每个用户的计数；count字段在聚合阶段被累积，但最终未体现在输出中，排序依据也是用户名而非贡献数量。若需要按贡献数排序或输出计数，需要在contributors.js的排序与输出环节自行扩展。

与发布流程中其他脚本的协同

contributor-list-generator并非孤立工具，它位于package/这一发布工具集合中，与相邻脚本构成一个相对完整的发布支持链路：

• changelog_to_schelp.sh：将 Markdown 格式的 changelog 转换为 SuperCollider 帮助系统使用的.schelp格式（生成title::、summary::、section::等标签）。贡献者名单的输出（users.join(", ")）可以直接作为这类 changelog/致谢段落的一部分；
• create_source_tarball.sh：按版本 tag 克隆源码、清理.git等冗余文件后打包为SuperCollider-x.x.x-Source.tar.bz2，并可生成 PGP 签名。它与贡献者名单脚本同属「版本发布前准备」阶段；
• package.json的main字段指向changelog.js，也佐证了该目录在设计上同时承载过 changelog 相关的辅助功能。

从仓库整体看，维护者在发布流程中的典型用法是：先通过本工具抓取某里程碑数据生成贡献者名单，再结合changelog_to_schelp.sh将更新日志转换为帮助文档格式，最后用create_source_tarball.sh产出发布包——三者共同服务于 CHANGELOG.md 与版本发布。

适用前提与注意事项

基于当前仓库的脚本实现，使用本工具时有几点需要明确的前提与限制：

1. 依赖 GitHub API 未认证配额：脚本直接调用api.github.com，未携带 token。按 GitHub 公开 API 的限制，未认证请求存在小时级速率配额（约 60 次/小时），本脚本 3 条 curl 命令通常可满足；若配额耗尽，curl 会返回包含API rate limit exceeded的错误响应，此时需要为 curl 追加认证头（如-H "Authorization: token ..."）。
2. 里程碑 ID 为数字而非名称：milestone参数必须使用里程碑的数字 ID，交互提示与脚本注释均已说明获取方法。
3. 分页上限为硬编码：Issue 最多 5 页（500 条）、PR 最多 2 页（200 条），超出部分不会被抓取；超大里程碑需要修改 fetch-data.sh 中的[1-5]、[1-2]区间。
4. 数据目录须先清理：contributors.js会读取所有已存在的issues-closed-*.json/pulls-closed-*.json，因此旧文件可能污染统计，README 因此强制要求先trash github-data/。
5. 运行环境：需要 Node.js（支持模板字符串，即 ES6+）与 lodash（由npm install安装）；fetch-data.sh需要 bash 与 curl。

小结

package/contributor-list-generator/用极简的「两个脚本 + 一个依赖」实现了从 GitHub 里程碑数据到贡献者名单的完整闭环：fetch-data.sh负责按里程碑抓取关闭的 Issue 与 PR 原始数据，contributors.js通过「closed 状态 + 合并校验」的过滤口径完成用户聚合与字母序输出。它既是 SuperCollider 发布工具链中的实用组件，也是一个结构清晰、易于改造的 GitHub API 数据统计参考实现——读者完全可以参照它，将其中的统计口径、分页抓取与聚合逻辑迁移到自己的项目发布流程中。

• 音频处理
• 编程语言