release: publish an ASF-compliant npm convenience artifact

[M4n5ter]

English

Part of #2974 — G8: npm convenience artifact.

Outcome

Publish the established maka-agent npm package as an ASF-compliant convenience artifact from the exact commit approved as the Apache Maka source release.

Release boundary

The signed source archive is the ASF release artifact and the object of the podling and IPMC votes. The source-RC npm workflow is a credential-free compatibility preflight: it builds and validates the package from the RC commit, but its tarball is not voted on, published, or carried into ASF distribution.

After both source votes approve the candidate, the product Release workflow creates v<version> at that approved commit. npm Stage builds and validates one publication tarball from the final tag, submits those exact bytes through the protected npm-release Environment and OIDC, and leaves public approval to a 2FA-protected maintainer. Finalize verifies the public registry bytes, integrity, signature, provenance, and dist-tag.

This follows Apache OpenDAL's incubating practice while retaining Maka's stronger staged-publishing and post-publication controls. The npm tarball does not need a separate ASF detached PGP signature, ASF SHA-512 sidecar, inclusion in dist/dev or dist/release, or byte identity with a pre-vote preflight build.

Repository implementation status

Repository files and workflows are complete after merged PR #3481. The package already has three maintainers with write access (m4n5ter, astrohan, and kunli666661), with an additional invitation pending for jackwener. The remaining work is external approval/configuration, G3 review, and execution against the real source RC and public package.

Exit criteria

• The final product tag, version, and commit identify the IPMC-approved source release; Stage validates and submits one tarball, and Finalize proves the public registry bytes match the Stage record.
• The complete production dependency closure rejects Category X, unresolved private workspaces, credentials, local paths, tests, fixtures, and development-only files.
• The npm artifact contains artifact-specific LICENSE, NOTICE, DISCLAIMER-WIP, README, and required third-party notices reviewed under G3 (legal: audit LICENSE and NOTICE for the first release artifacts #3270).
• The npm README/version page displays the complete canonical disclaimer from the release commit's DISCLAIMER-WIP; package metadata uses Apache Maka (Incubating) branding and declares Apache-2.0.
• Before the first compliant publication, obtain and record explicit mentor or ASF Brand confirmation that maka-agent may be retained; if it is not approved, handle renaming separately without speculative migration machinery.
• The source-RC preflight never publishes or moves a dist-tag; npm Stage is possible only after source approval and final product-tag creation.
• At least two PPMC npm maintainers hold write access to the unscoped maka-agent package; npm organization ownership is not used as a criterion for an unscoped package.
• Trusted Publisher, 2FA recovery, approval and rollback procedures, and the GitHub npm-release Environment can be operated independently by the PPMC.
• Clean-install acceptance passes on supported Linux, macOS, and Windows environments using the exact public tarball.

Existing work

• Publish the Maka CLI/TUI to npm as maka-agent #3166 owns the standalone npm product-package behavior.
• fix(release): carry DISCLAIMER-WIP in the npm CLI tarball #3220 adds DISCLAIMER-WIP to CLI tarballs.
• Merged feat(release): unify Desktop and CLI product releases #3222 and feat(release): prepare ASF npm candidates #3335 establish product-release identity, final-tag publication authority, staged publishing, OIDC, 2FA, registry byte/signature/provenance verification, Finalize, and the source-RC package preflight.
• Merged PR refactor(release): align npm preflight with ASF practice #3481 removes the unnecessary candidate handoff/SHA-512/record layer, documents the correct publication boundary and OpenDAL precedent, injects the canonical DISCLAIMER-WIP into the npm README, and adds package branding.
• legal: audit LICENSE and NOTICE for the first release artifacts #3270 remains the authority for artifact-specific legal-file and third-party-material review; this issue does not duplicate or pre-judge that audit.

Package-name decision

The implementation currently retains maka-agent, but the project must obtain and record explicit mentor or ASF Brand confirmation before the first compliant publication. The Incubator npm guide shows an apache-<project> name, while Apache OpenDAL published the unprefixed opendal package throughout incubation. OpenDAL's package predates its incubation entry whereas maka-agent does not, so the precedent supports requesting the current name but does not settle Maka's naming decision.

Out of scope

• Publishing internal @maka/* workspaces as public packages.
• Desktop installers and standalone Desktop artifacts.
• Treating the npm package as the official ASF source release.
• Replacing G3's artifact-specific legal review.

References

• Incubator distribution guidelines — NPM
• Incubator disclaimer policy
• ASF release policy
• ASF third-party license policy
• OpenDAL v0.44.0 incubating release guide
• OpenDAL v0.44.0 Node.js workflow
• OpenDAL 0.44.0 source artifacts in the ASF archive
• OpenDAL current Node.js release workflow

Ownership

M4n5ter owns delivery and coordination of the complete G8 outcome. This does not replace legal conclusions from G3, publication approval by the PPMC, or authoritative guidance from mentors, the IPMC, ASF Brand, or ASF Legal Affairs.

简体中文

#2974 的一部分——G8：npm convenience artifact。

目标结果

从获批为 Apache Maka 源码 release 的精确 commit 发布既有 maka-agent 包，使其成为符合 ASF 要求的 npm convenience artifact。

发布边界

签名后的源码归档是 ASF release artifact，也是 podling 与 IPMC 的投票对象。source RC 阶段的 npm workflow 是无凭据的兼容性预检：它从 RC commit 构建并验证包，但该 tarball 不参加投票、不公开发布，也不进入 ASF distribution。

两轮源码投票通过后，产品 Release workflow 在同一获批 commit 创建 v<version>。npm Stage 从最终 tag 构建并验证唯一正式发布 tarball，通过受保护的 npm-release Environment 与 OIDC 提交这些精确字节，并由启用 2FA 的 maintainer 人工批准公开。Finalize 校验公共 registry 字节、integrity、signature、provenance 与 dist-tag。

这与 Apache OpenDAL 孵化期实践一致，同时保留了 Maka 更严格的 staged publishing 与发布后控制。npm tarball 不需要单独的 ASF PGP detached signature、ASF SHA-512 sidecar、进入 dist/dev 或 dist/release，也不需要与投票前预检构建保持字节一致。

仓库实现状态

PR #3481 合并后，仓库文件与 workflows 已经完成。npm package 已有 m4n5ter、astrohan 和 kunli666661 三位 maintainers 持有 write access，另有 jackwener 的邀请等待接受。剩余工作是外部认可与配置、G3 审查，以及针对真实 source RC 和公共 package 的发版执行。

完成条件

• 最终产品 tag、版本与 commit 指向 IPMC 获批源码 release；Stage 验证并提交唯一 tarball，Finalize 证明公共 registry 字节与 Stage 记录一致。
• 完整生产依赖闭包拒绝 Category X、未解析私有 workspace、凭据、本地路径、tests、fixtures 和仅开发文件。
• npm artifact 包含经 G3（legal: audit LICENSE and NOTICE for the first release artifacts #3270）审核的 artifact-specific LICENSE、NOTICE、DISCLAIMER-WIP、README 和必需第三方 notices。
• npm README/version 页面展示来自 release commit DISCLAIMER-WIP 的完整权威 Incubator disclaimer；package metadata 使用 Apache Maka (Incubating) 品牌并声明 Apache-2.0。
• 第一次合规发布前，取得并记录 mentors 或 ASF Brand 对继续使用 maka-agent 的明确认可；如果未获认可，再单独处理改名，不增加假想迁移机制。
• source-RC 预检绝不发布或移动 dist-tag；只有源码获批并创建最终产品 tag 后才允许 npm Stage。
• 至少两位 PPMC npm maintainers 对 unscoped maka-agent package 持有 write access；unscoped package 不以 npm organization ownership 作为关闭条件。
• Trusted Publisher、2FA 恢复、审批与回滚流程以及 GitHub npm-release Environment 可由 PPMC 独立操作。
• 使用精确公共 tarball，在支持的 Linux、macOS 与 Windows 环境通过全新安装验收。

已有工作

• Publish the Maka CLI/TUI to npm as maka-agent #3166 负责独立 npm 产品包行为。
• fix(release): carry DISCLAIMER-WIP in the npm CLI tarball #3220 让 CLI tarball 包含 DISCLAIMER-WIP。
• 已合并的 feat(release): unify Desktop and CLI product releases #3222 与 feat(release): prepare ASF npm candidates #3335 建立了产品 release identity、最终 tag 发布 authority、staged publishing、OIDC、2FA、registry byte/signature/provenance 校验、Finalize，以及 source-RC package 预检。
• 已合并 PR refactor(release): align npm preflight with ASF practice #3481 删除不必要的 candidate handoff/SHA-512/record 层，记录正确发布边界与 OpenDAL 先例，将权威 DISCLAIMER-WIP 注入 npm README，并补齐 package 品牌。
• legal: audit LICENSE and NOTICE for the first release artifacts #3270 仍是 artifact-specific 法律文件与第三方材料审查的 authority；本 issue 不重复或预判该审计。

包名决定

当前实现继续使用 maka-agent，但第一次合规发布前必须取得并记录 mentors 或 ASF Brand 的明确认可。Incubator npm 指南给出了 apache-<project> 名称；Apache OpenDAL 在整个孵化期间发布未加前缀的 opendal，但该包早于 OpenDAL 进入孵化器，而 maka-agent 并非如此。因此这个先例支持请求保留当前名称，不能替 Maka 解决命名判断。

不在范围内

• 将内部 @maka/* workspace 作为公共包发布。
• Desktop 安装包和独立 Desktop artifacts。
• 将 npm 包视为 ASF 官方源码 release。
• 替代 G3 的 artifact-specific 法律审查。

参考资料

• Incubator 分发指南——NPM
• Incubator 免责声明政策
• ASF 发版政策
• ASF 第三方许可证政策
• OpenDAL v0.44.0 孵化期发布指南
• OpenDAL v0.44.0 Node.js workflow
• ASF archive 中的 OpenDAL 0.44.0 源码 artifacts
• OpenDAL 当前 Node.js 发布 workflow

负责人边界

M4n5ter 负责完整 G8 结果的交付与协调。这不会取代 G3 的法律结论、PPMC 的发布批准，以及 mentors、IPMC、ASF Brand 或 ASF Legal Affairs 的权威指导。

[M4n5ter]

English

Claiming coordination and implementation ownership for G8.

This work will reuse the existing npm package path in #3166, the merged disclaimer coverage from #3220, and the release-identity/staging foundation in #3222 rather than creating a parallel publication system. The immediate sequencing is:

1. finish G2's first successful Prepare ASF source candidate run from reviewed main;
2. audit the current npm candidate against release: publish an ASF-compliant npm convenience artifact #3275's artifact boundary and identify only the remaining ASF-specific gaps;
3. implement and verify one immutable npm candidate tied to the approved source-release identity.

This assignment owns delivery and coordination of the complete G8 outcome. It does not replace mentor/IPMC decisions on the npm package name, legal-file conclusions from G3, or PPMC-controlled credentials and publication approval.

简体中文

认领 G8 的协调与实现责任。

这项工作会复用 #3166 的现有 npm package 路径、#3220 已合并的免责声明覆盖，以及 #3222 的发版身份与 staging 基础，不会另建一套平行发布系统。近期顺序为：

1. 先完成 G2 从经过审查的 main 成功运行一次 Prepare ASF source candidate；
2. 按 release: publish an ASF-compliant npm convenience artifact #3275 的 artifact 边界审计当前 npm candidate，只识别仍缺失的 ASF 专属事项；
3. 实现并验证一个绑定获批源码 release 身份的不可变 npm candidate。

本次 assignment 负责完整 G8 结果的交付与协调，但不会取代 mentors/IPMC 对 npm package 名称的判断、G3 的法律文件结论，以及由 PPMC 控制的凭据与发布批准。

[M4n5ter]

English

I updated this issue after comparing the ASF Incubator npm guidance with Apache OpenDAL's incubating release practice, and opened draft PR #3481 for the implementation correction.

The previous scope treated the pre-vote npm tarball as if it were another ASF release artifact: immutable handoff bytes, an ASF SHA-512 sidecar, and a closed candidate record. That is not required for an npm convenience artifact and duplicated authority already owned by the signed source release and the post-approval npm Stage/Finalize path.

The revised boundary does not weaken source-release controls: the source RC remains signed, immutable, and voted on. npm preflight remains bound to its exact RC tag and commit but has no publication authority. After approval, npm is built from the final tag at that same commit, then protected by staged publishing, OIDC, human 2FA approval, registry integrity/signature/provenance verification, and platform acceptance.

The naming conclusion is now deliberately narrower: the implementation keeps maka-agent, but the project must obtain and record explicit mentor or ASF Brand confirmation before the first compliant publication. OpenDAL published opendal throughout incubation, but that package predates OpenDAL's incubation entry whereas maka-agent does not. The precedent supports asking to retain the name; it does not settle Maka's decision.

简体中文

我对照 ASF Incubator npm 指南与 Apache OpenDAL 孵化期发布实践后更新了本 issue，并创建 draft PR #3481 实现这次校正。

旧范围把投票前 npm tarball 当成了另一份 ASF release artifact，要求冻结交接字节、ASF SHA-512 sidecar 和闭合 candidate record。这不是 npm convenience artifact 的必需条件，也与签名源码 release 及获批后的 npm Stage/Finalize 重复建立 authority。

新边界不会削弱源码发版控制：source RC 仍然需要签名、保持不可变并接受投票。npm 预检仍精确绑定 RC tag 与 commit，但没有发布权限。获批后，npm 从同一 commit 的最终 tag 构建，再由 staged publishing、OIDC、人工 2FA、registry integrity/signature/provenance 校验和平台验收保护。

包名结论现已收紧：当前实现继续使用 maka-agent，但第一次合规发布前必须取得并记录 mentors 或 ASF Brand 的明确认可。OpenDAL 在孵化期间发布 opendal，但该包早于 OpenDAL 进入孵化器，而 maka-agent 并非如此。这个先例支持提出保留请求，不能替 Maka 解决命名判断。