apache / apache/polaris

Site: Keep documentation and downloads information at a reasonable size

Open
#3,039 1 comment 0 reactions 0 assignees View on GitHub
enhancement stale
Dominant language
Java
Stars
2.1k
Forks
522
Avg merge
1d 22h
Merged PRs (30d)
137

Description

### Is your feature request related to a problem? Please describe.

The (current state of) https://polaris.apache.org/ web site has a couple of Polaris release related pieces of information:
* Versioned docs
* documentation per release version
* documentation of the latest state on the `main` branch
* accessible via the "Documentation" drop-down nav-bar menu
* Releases (downloads) page, containing
* Links to release artifacts
* Changelog for the release
* Search
* All pages, including the docs for old releases, are indexed for the search functionality

There are some elements that could or even should be improved.
* Search: There are a couple of options to limit the amount of search results:
* Exclude all but the in-dev and latest release from the search index
* Exclude all but the in-dev and ["active" releases]((https://github.com/apache/polaris/blob/74c58354c4182e76fa3e77d1e9faa07fbde71e52/site/hugo.yaml#L66)
* Releases (downloads) page.
* Split the single page, as also [proposed here](https://github.com/apache/polaris/pull/2928#pullrequestreview-3457451706)
* Either:
* Have a separate page showing releases. Maybe split into active and older releases.
* Move the individual download/changelog information to the versioned docs
* "Documentation" drop-down menu
* Should it list all ever released versions?
* Should it list all ["active" releases]((https://github.com/apache/polaris/blob/74c58354c4182e76fa3e77d1e9faa07fbde71e52/site/hugo.yaml#L66)
* In either "yes" for the above: a separate page showing the links for the "older" releases would be nice.

Ideally, a job that's part of the automated-release-workflow should help by creating PRs do perform changes against the web site content and config on the `main` branch.
Some changes, depending on the outcome(s) of the above bullet-list options, like adding a front-matter option to exclude pages from the search index, affect a lot of files.

### Describe the solution you'd like

_No response_

### Describe alternatives you've considered

_No response_

### Additional context

_No response_

Contributor guide

Open the contributing guide

Research direction

Start with site/hugo.yaml and the automated-release-workflow, then review the proposed split in PR 2928. Decide which releases appear in navigation, downloads, and search, and document the chosen approach before changing the site content or configuration. Done means the site remains manageable and release updates can be automated.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, hugo, yaml
Domain
documentation, release, search
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.