Skip to content

infra: publish the podling website at maka.apache.org from the existing Maka site #3404

Open
Task
Open
infra: publish the podling website at maka.apache.org from the existing Maka site#3404
Task
Assignees
Astro-Han
Labels
documentationImprovements or additions to documentation

Description

@Astro-Han
Astro-Han
opened on Aug 21, 2026
English

Part of #2974 — supports #3272 (G5: Incubator branding and release surfaces).

Outcome

maka.apache.org serves a PPMC-reviewed podling website, published through ASF infrastructure, that identifies the project as Apache Maka (Incubating) and provides an ASF-compliant source download path with KEYS and verification instructions.

This is a migration and re-branding of the existing site, not a new build. maka-agent/maka-agent.github.io is an Astro static site currently deployed to GitHub Pages behind the maka-agent.com custom domain, with Cloudflare as authoritative DNS.

Prior art: Apache OpenDAL

OpenDAL, a mentor's project, publishes its site from the main repository rather than a separate one. The mechanics are worth copying because they are known to work with ASF infrastructure:

  • The site source lives in apache/opendal under website/ (Docusaurus).
  • .github/workflows/docs.yml builds it and pushes website/build to the gh-pages branch with force_orphan: true.
  • .asf.yaml carries publish: whoami: gh-pages, which is what makes asfyaml serve the branch at opendal.apache.org.
  • The same workflow pushes RC builds to site/<name>-staging, and .asf.yaml carries staging: autostage: site/*, so a release candidate's site can be reviewed before it goes live.
  • website/src/pages/download.mdx is short: source artifacts are the release, a link to the latest source release, links to the ASF archive and the incubator archive, KEYS, and gpg --import / gpg --verify / shasum -a 512 -c instructions.
  • The Docusaurus footer carries the ASF logo and the License, Events, Privacy, Security, and Sponsorship links, plus the trademark line in the copyright.

Follow this layout unless something about Maka makes it unworkable. The one part that does not carry over is OpenDAL's release path for crates.io and Maven staging, which Maka does not need. Maka also does not use ™, since the podling name search has not concluded.

Hosting decision

I evaluated Cloudflare Pages and R2 as the production host for maka.apache.org. They are technically capable, but I will follow the existing ASF publication path rather than request an Infrastructure exception. The free tier does not change the ownership and governance requirements for an official Apache website.

  • I will keep apache/maka as the source authority and place the Astro website under website/.
  • I will use GitHub Actions to build the static output and push it to an ASF website publish branch. .asf.yaml will publish that branch to maka.apache.org.
  • I will use ASF website staging as the authoritative pre-production review path.
  • I will keep official source releases on the ASF distribution and mirror infrastructure. The website will link the source archive, KEYS, signatures, checksums, and verification instructions rather than host release files itself.
  • I will keep npm and Desktop convenience artifacts separate from the official source release and label them accordingly.
  • I will not introduce R2 for the static website. It is unnecessary here and would add another account, credential, billing, and operational authority outside the ASF publication path.
  • I will reuse the existing Astro implementation and design assets where their provenance and IP coverage are confirmed. I will rewrite pre-Apache authorities and branding, but will not couple the migration to a full visual redesign.

Implementation order

  1. I will ask the mentors/PPMC to confirm the IP coverage for the existing site's code, copy, fonts, images, and design assets.
  2. I will import the approved Astro source into apache/maka/website/ and integrate it with the root workspace and lockfile.
  3. I will establish the minimum official surfaces: homepage, documentation and community links, ASF-compliant downloads and verification, security, privacy, license, Incubator disclaimer, and ASF footer.
  4. I will add the build workflow, publish branch, .asf.yaml staging and publishing configuration, and deployment-specific validation.
  5. I will verify the staged site end to end, publish it to maka.apache.org, update repository metadata, and then propose whether maka-agent.com should redirect or be retired.

Current state

  • The site repository carries no LICENSE file and lives outside the apache organization.
  • On main, src/pages contains only index.astro and 404.astro.
  • The download, documentation, architecture, security, releases, and Chinese overview pages exist only in the unmerged draft maka-agent.github.io#1, which its author marks as visually unfinished.
  • docs: connect project metadata to public website #2924 depends on that draft and is therefore blocked as well.
  • maka.apache.org currently returns 404.

Exit criteria

  • Mentors confirm how the site's code, copy, and design assets are covered — by the software grant tracked in legal: close incoming IP provenance for the first Apache release #3268 or by a separate Incubator IP clearance — before any content moves into an ASF repository.
  • The migrated site carries LICENSE and NOTICE, and third-party assets such as fonts and images have recorded provenance.
  • The site source lives in an ASF repository, by default apache/maka under website/, following OpenDAL rather than creating a separate site repository.
  • A workflow builds the site and pushes the built output to a publish branch, and .asf.yaml gains the matching publish: entry, extending the seam established in chore: add .asf.yaml for ASF infrastructure self-service #3262.
  • maka.apache.org serves that site instead of 404.
  • A staging path exists for reviewing a release candidate's site before it is published.
  • The homepage identifies the project as Apache Maka (Incubating) on first mention and carries the full Incubator disclaimer.
  • Every page carries the ASF footer: License, Events, Privacy, Security, Sponsorship, and trademark attribution.
  • A downloads page presents the official Apache source release as the release, links KEYS, publishes SHA-512 and detached signatures, and gives working GPG and checksum verification steps, following OpenDAL's download.mdx.
  • The downloads page separates convenience artifacts from the source release and states that they are not the release.
  • The PPMC decides what happens to maka-agent.com and to the GitHub Pages deployment: retire, redirect, or keep as a separate product site under the ASF branding rules for podling names and non-ASF domains.

Sequencing

The downloads page is the part #3272 depends on, and its page skeleton currently sits inside an unmerged draft whose blocker is visual design. Do not couple the ASF downloads page to that design work. OpenDAL's download page is roughly one screen of prose and two shell snippets; land an equivalent minimal /downloads/ page first, and let any product-site visual redesign proceed on its own track.

The downloads page cannot list real artifacts until a release candidate exists, but its structure, KEYS link, and verification instructions can and should be reviewed before the first vote. OpenDAL's verify.md is a usable model for the reviewer-facing checklist.

Out of scope

References

Ownership

I have claimed the end-to-end implementation. I will ask the mentors/PPMC to confirm IP coverage and public governance decisions where required; my implementation ownership does not replace those decisions.

AI use: I used Codex to assist with policy research and drafting this update. I reviewed the cited policies and own the public change.

简体中文

#2974 的一部分——支撑 #3272（G5：孵化器品牌与发版界面）。

目标结果

maka.apache.org 提供经 PPMC 审查、由 ASF 基础设施发布的 podling 网站，标识项目为 Apache Maka (Incubating)，并提供符合 ASF 要求的源码下载入口、KEYS 和验包说明。

这是对现有站点的迁移和重新品牌化，不是新建。maka-agent/maka-agent.github.io 是一个 Astro 静态站，目前通过 GitHub Pages 部署在自定义域 maka-agent.com 下，DNS 权威在 Cloudflare。

参照：Apache OpenDAL

OpenDAL 是本项目 mentor 的项目，它把网站源码放在主仓库而不是单独仓库。这套机制已经在 ASF 基础设施上跑通，值得直接照搬：

  • 站点源码位于 apache/opendal 的 website/ 目录（Docusaurus）。
  • .github/workflows/docs.yml 构建后，用 force_orphan: true 把 website/build 推到 gh-pages 分支。
  • .asf.yaml 中的 publish: whoami: gh-pages 让 asfyaml 把该分支发布到 opendal.apache.org。
  • 同一个 workflow 把 RC 构建推到 site/<name>-staging，配合 .asf.yaml 的 staging: autostage: site/*，使发版候选的站点可以先审查再上线。
  • website/src/pages/download.mdx 很短：声明源码 artifacts 才是 release，给出最新源码 release 链接、ASF archive 与 incubator archive、KEYS，以及 gpg --import / gpg --verify / shasum -a 512 -c 说明。
  • Docusaurus 页脚带 ASF logo 和 License、Events、Privacy、Security、Sponsorship 链接，商标声明写在 copyright 行里。

除非 Maka 有具体因素导致行不通，否则按这套布局做。唯一不适用的是 OpenDAL 面向 crates.io 和 Maven staging 的发版路径，Maka 不需要。Maka 也不使用 ™，因为 podling 名称搜索尚未完成。

托管决策

我评估了用 Cloudflare Pages 和 R2 托管 maka.apache.org 的方案。它们在技术上可行，但我会沿用 ASF 现有的官网发布链路，而不是为 Cloudflare 申请 Infrastructure 例外。免费额度不会改变 Apache 官方网站的所有权和治理要求。

  • 我会以 apache/maka 作为官网源码的权威来源，将 Astro 站点放在 website/。
  • 我会用 GitHub Actions 构建静态产物并推送到 ASF 官网发布分支，再由 .asf.yaml 发布到 maka.apache.org。
  • 我会使用 ASF website staging 作为正式发布链路的权威预发布验收环境。
  • 我会继续通过 ASF distribution 和镜像系统分发官方源码 release。官网只链接源码包、KEYS、签名、校验和与验包说明，不自行托管 release 文件。
  • 我会把 npm 和 Desktop convenience artifacts 与官方源码 release 分开，并明确标注其性质。
  • 我不会为静态官网引入 R2。这里不需要对象存储，而且它会在 ASF 发布链路之外增加账号、凭据、账单和运维权威。
  • 对来源和 IP 覆盖已确认的 Astro 实现与设计资产，我会直接迁移复用。我会重写进入 Apache 前的品牌和权威链接，但不会把迁移绑定在一次完整的视觉重做上。

实施顺序

  1. 我会请 mentors/PPMC 确认现有官网代码、文案、字体、图片与设计资产的 IP 覆盖方式。
  2. 我会将获准迁移的 Astro 源码引入 apache/maka/website/，接入根 workspace 和 lockfile。
  3. 我会建立最小完整的正式页面：首页、文档与社区入口、符合 ASF 要求的下载与验包页、安全、隐私、许可证、Incubator disclaimer 和 ASF 页脚。
  4. 我会增加构建 workflow、发布分支、.asf.yaml staging/publish 配置及部署契约验证。
  5. 我会对 staging 站点做端到端验收，发布到 maka.apache.org，更新仓库元数据，然后再提出 maka-agent.com 跳转或下线的方案。

现状

  • 站点仓库没有 LICENSE 文件，且不在 apache 组织下。
  • main 上 src/pages 只有 index.astro 和 404.astro。
  • 下载、文档、架构、安全、releases 和中文概览页面只存在于未合并的 draft maka-agent.github.io#1 中，作者自述其设计尚未完成。
  • docs: connect project metadata to public website #2924 依赖该 draft，因此同样处于阻塞状态。
  • maka.apache.org 目前返回 404。

完成条件

  • 在任何内容进入 ASF 仓库之前，由 mentors 确认站点代码、文案和设计资产的授权覆盖方式——是包含在 legal: close incoming IP provenance for the first Apache release #3268 追踪的软件捐赠中，还是需要单独的 Incubator IP clearance。
  • 迁移后的站点具备 LICENSE 和 NOTICE，字体、图片等第三方资产有可查的来源记录。
  • 站点源码进入 ASF 仓库，默认放在 apache/maka 的 website/ 目录，照 OpenDAL 的做法，而不是新建独立站点仓库。
  • 由 workflow 构建站点并把产物推到发布分支，.asf.yaml 增加对应的 publish: 配置，扩展 chore: add .asf.yaml for ASF infrastructure self-service #3262 建立的接缝。
  • maka.apache.org 提供该站点，不再返回 404。
  • 存在 staging 路径，可在发版候选的站点上线前进行审查。
  • 首页首次提及时标识为 Apache Maka (Incubating)，并展示完整 Incubator disclaimer。
  • 所有页面带有 ASF 页脚：License、Events、Privacy、Security、Sponsorship 和商标归属。
  • 下载页把官方 Apache 源码 release 作为 release 呈现，链接 KEYS，公布 SHA-512 和 detached signature，并给出可实际执行的 GPG 与校验步骤，格式参照 OpenDAL 的 download.mdx。
  • 下载页把 convenience artifacts 与源码 release 分开，并说明它们不是 release。
  • PPMC 决定 maka-agent.com 和 GitHub Pages 部署的去向：下线、跳转，或按 ASF 关于 podling 名称与非 ASF 域名的品牌规则保留为独立产品站。

推进顺序

下载页是 #3272 依赖的部分，而它的页面骨架目前位于一个因视觉设计而阻塞的未合并 draft 中。不要把 ASF 下载页绑定在那项设计工作上：OpenDAL 的下载页只有大约一屏文字加两段 shell 命令，先落一个同等规模的最小 /downloads/ 页，产品站的视觉重做单独推进。

在出现发版候选之前，下载页无法列出真实 artifacts，但它的结构、KEYS 链接和验包说明可以、也应当在第一次投票前完成审查。面向 reviewer 的检查清单可参照 OpenDAL 的 verify.md 。

不在范围内

参考资料

负责人边界

我已认领端到端实施。对于 IP 覆盖和公开治理决策，我会在需要时请 mentors/PPMC 确认；我的实施责任不会替代这些决策。

AI 使用：我使用 Codex 协助政策调研和本次更新的起草。我已审阅引用的政策，并对这次公开更新负责。

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

Task

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions