Skip to content

docs: add a Download page for the source release - #7446

Open
andygrove wants to merge 4 commits into
apache:mainfrom
andygrove:docs-download-page
Open

andygrove wants to merge 4 commits into
apache:mainfrom
andygrove:docs-download-page

Conversation

@andygrove

@andygrove andygrove commented Nov 3, 2026 •

Copy link
Copy Markdown
Member

Which issue does this PR close?

No existing issue.

Rationale for this change

ASF release policy requires every project to provide a Project Download Page, and requires release announcements to link to it. The page must link the source release through the mirror system (closer.lua), and the signature, checksum and KEYS files must be served from downloads.apache.org, not from a mirror.

Comet has no such page. The only link to the published source release is in the "Building from source" user guide, and it points at the raw dist.apache.org/repos/dist/release/ SVN path. It has no signature, checksum or KEYS link, and no instructions for verifying the download.

What changes are included in this PR?

  • Add docs/source/download.md, linked from the site navigation. It lists the 1.2.0 source tarball (via closer.lua), the .asc and .sha512 files and KEYS (via downloads.apache.org), verification instructions, a note that the Maven Central jars are a convenience, and a pointer to archive.apache.org for older releases.
  • Point "Using a Published Source Release" in user-guide/latest/source.md at the Download page.
  • In release_process.md, add an "Update the download page" step and a checklist item before the vote is closed, so the page is live before the announcement email, which must link to it. The step says to wait at least an hour after the tarball upload before merging, and to check the mirror, signature, checksum and KEYS links. The version on the page is hard-coded rather than templated, because the docs promotion in generate-versions.py happens before the vote and the page must not link an unpublished release.

The user guide links on the page (user-guide/1.1/...) point at 1.1 because the 1.2 user guide has not been promoted yet. They should be switched to 1.2 when that happens.

How are these changes tested?

Documentation only. Prettier passes on the changed files. The docs have not been built with Sphinx, and the download URLs have not been fetched because they follow the layout produced by dev/release/release-tarball.sh. They should be checked once the page is live, in particular https://downloads.apache.org/datafusion/KEYS.

@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Nov 3, 2026
ASF release policy requires a project download page that links the source
release through the mirror system, with the signature, checksum and KEYS
served from downloads.apache.org. The user guide linked to the raw
dist.apache.org SVN path and gave no way to verify the download.

Add a Download page, point the build-from-source guide at it, and add a
post-release step to update the page and to link it from the announcement.
@andygrove
andygrove marked this pull request as ready for review November 3, 2026 01:16
@andygrove
andygrove requested a review from manuzhang November 3, 2026 14:13
Comment thread docs/source/download.md Outdated

Pre-built Comet jar files for Linux are published to
[Maven Central](https://central.sonatype.com/namespace/org.apache.datafusion) as a convenience. They are built from
the source release above. See the [installation guide](https://datafusion.apache.org/comet/user-guide/1.1/installation.html) for the links and for the

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The installation guide still points to 1.1.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed. The page linked the 1.1 user guide, so a reader of the 1.2.0 download page landed on the older docs. "Building Comet From Source" and the installation guide now link user-guide/latest/ by path, so they follow the release and need no edit when the page is updated. The release process no longer asks for the user guide links to be changed.

- The release version
- A link to the release notes / changelog
- A link to the download page or Maven coordinates
- A link to the [Download](https://datafusion.apache.org/comet/download.html) page for the source release (required by

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The style guide says pages under docs/source link to other pages by path. Can we use paths where possible?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done. The two links to the Download page in release_process.md and the one in source.md are paths (../download.md and ../../download.md), as is the link from the download page to the guide pages (aeea29c). I also merged main.

@comphead comphead left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One comment on where the new guide links land.

Comment thread docs/source/download.md Outdated
[KEYS](https://downloads.apache.org/datafusion/KEYS) file.

The release notes are in the [changelog](changelog/1.2.0.md).
See [Building Comet From Source](user-guide/latest/source.md) for how to build the tarball.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the site user-guide/latest/ is the development snapshot. generate_docs strips the <!-- IF_RELEASE --> blocks there and keeps the <!-- IF_SNAPSHOT --> ones, so this link opens a section that says "Published source releases are only available for released versions", and the installation guide link on line 56 opens the nightly snapshot jars section. The release text with the tarball commands is only in the versioned copy that publish_released_version builds from branch-1.2. Could both links point at user-guide/1.2/ instead, with the release step that updates them kept? Sphinx builds from docs/temp, where that directory exists, but I have not built the docs to confirm that the path resolves.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed. "Building Comet From Source" and the installation guide now link user-guide/1.2/ by path, and the release step again says to update the user guide links (23c9d88). I built the docs from docs/temp to check: the path resolves to user-guide/1.2/source.html and user-guide/1.2/installation.html, and those pages have the release text with the tarball commands, while the latest copies have the snapshot text you described. The build also showed that the page's license header was never closed, so the whole Download page was rendering as an HTML comment with no title. That is fixed in the same commit.

…s license header

user-guide/latest/ on the site is the development snapshot, built with the
IF_RELEASE blocks stripped, so the Building From Source and installation
guide links opened snapshot text instead of the 1.2.0 release instructions.
Link user-guide/1.2/ by path, which resolves because the docs are built from
docs/temp where generate-versions.py adds that directory, and restore the
release step that updates these links.

The license header comment was never closed, so the whole page rendered as
an HTML comment with no title. Close it, and reword a shell comment that
Pygments failed to lex.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants