nixpkgs-package-upstream

把软件包提交到上游 nixpkgs（通用）

把仓库里自己打的包变成 nixpkgs 的一部分。

本技能只包含与仓库无关的通用方法。仓库特有的环节（多语文档同步、维护日志、 自检登记等）由仓库适配层提供——见文末。

顺序不能换：评估 → 审计 → dry-run → 实操。跳步的代价在最后一节。

---

第 0 步：先同步，再采信

任何「现在的 nixpkgs 是什么样」的结论，都要现取。

gh api repos/NixOS/nixpkgs/commits --jq '.[0].sha'   # 取 HEAD，写进你的报告

走过的坑：本地那份 nixpkgs 快照的 CONTRIBUTING.md 里没有 AI 政策一节， 而 upstream master 里有。凭快照下结论就会漏掉整条最关键的硬要求。 文档结构会漂移——doc/contributing/ 目录现在已不存在， 只剩一个跳转存根 doc/contributing.md。路径必须实测，不能凭记忆。

同时把基线写进报告：哪一刻、哪个 commit。这决定了你的结论什么时候过期。

---

第 1 步：评估可行性（每个包一条，逐条给证据）

六问，任一答「否」就先别做：

① 它已经在 nixpkgs 里了吗？

gh api "repos/NixOS/nixpkgs/contents/pkgs/by-name/${shard}/${name}/package.nix?ref=master"
# 404 = 不在。200 = 在，那就只能提 update，不能提 init。

shard = 包名前两个字符的小写。别只查这一条路径—— 包也可能在类别目录里（pkgs/<类别>/<包名>/default.nix）。 再用属性名求值一次最稳：

nix eval --raw "path:<nixpkgs>#${name}.name"   # 报 NOT-A-PACKAGE 就是没有

② 曾经进过 nixpkgs、后来被删了吗？

gh api -X GET search/commits -f q="repo:NixOS/nixpkgs ${name}" --jq .total_count
gh api -X GET search/issues  -f q="repo:NixOS/nixpkgs ${name}" --jq .total_count

被删过的要先找删除理由（通常 包名: remove），理由可能就是现在仍然成立的理由。 搜索全 0 也不能反过来说「绝不存在过」—— 证据为负不是证明，要在报告里把这个区别写清楚。

走过的坑：一个包定义里的注释写着「nixpkgs 已不再提供它」， 而九条独立取证全是 0。真实来源是我们自己仓库的 CI workflow 记混了。 仓库里的自述会过期，它不是证据。

③ 有在途 PR 吗？ 这一条最容易白干。

gh api -X GET search/issues -f q="repo:NixOS/nixpkgs is:pr ${name}" --jq '.total_count, .items[].title'

要按「上游项目名」而不是「我们的包名」搜。 同一个软件的包名可能是别的写法—— 见过的实例：我们叫 dsh，nixpkgs 里三个在途 PR 都叫 deepseek-harness。

④ 许可能指认吗？——必须是那个 tag 里的文件

这是最容易被跳过、也最容易被审阅者当场卡住的一条。

要检查的是「我们实际取源的那个 tag/rev」里有没有许可，不是仓库的 main 分支。

走过的坑：某个包的 main 上有 LICENSE（最近才加的）， 而我们取源的 tag 比那次提交早十八天——tag 里没有许可文件。

但「没有 LICENSE 文件」不等于「没有许可」。 先找这三处，再决定要不要向上游要：

1. 源文件头：# SPDX-License-Identifier: <SPDX 表达式>。 直接在构建出来的产物里 grep（grep -rl SPDX-License-Identifier $out）， 比读仓库可靠——它证明的是我们真正取到的那份源码。
2. 清单文件：Python 的 pyproject.toml、Blender 插件的 blender_manifest.toml、 Node 的 package.json 等，常带 license / SPDX 字段。
3. 上游 issue 里有没有人问过：搜 license，看维护者怎么答的。 先例：某包有人提过「仓库没有许可文件」，维护者回 「licence is in the individual files」并随后补了 LICENSE——那条 issue 就是最有力的依据， 引它比引 main 上那份后加的文件强得多，而且说明不需要再开一条（有人做过的事不要重复做）。