Publish 1.0.0 documents by flyrain · Pull Request #1910 · apache/polaris

flyrain · 2025-06-18T22:45:47Z

We published the 0.9 doc after the release(#1175). Similarly, I will make this PR ready to review once 1.0 release was done.
Local test works well:

Copilot

Pull Request Overview

This PR publishes the updated documentation for the Polaris 1.0.0 release, reflecting new features, deployment guides, and configuration details.

Added new documentation pages for Polaris Spark client, management service, catalog service, metastores, and various getting-started guides.
Introduced deployment guides for AWS, Azure, GCP and updated detailed configuration and production guidelines.

Reviewed Changes

Copilot reviewed 20 out of 28 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
site/content/in-dev/1.0.0/polaris-spark-client.md	New documentation for the Polaris Spark client.
site/content/in-dev/1.0.0/polaris-management-service.md	Added documentation for the Polaris Management Service.
site/content/in-dev/1.0.0/polaris-catalog-service.md	Added documentation for the Catalog API Spec.
site/content/in-dev/1.0.0/metastores.md	New documentation detailing metastores configuration and usage.
site/content/in-dev/1.0.0/getting-started/using-polaris.md	Guide for using Polaris via CLI and API.
site/content/in-dev/1.0.0/getting-started/quickstart.md	Quickstart guide for deploying Polaris locally and via Docker.
site/content/in-dev/1.0.0/getting-started/install-dependencies.md	Installation guide covering prerequisites.
site/content/in-dev/1.0.0/getting-started/deploying-polaris/quickstart-deploy-gcp.md	Deployment guide for Google Cloud Platform.
site/content/in-dev/1.0.0/getting-started/deploying-polaris/quickstart-deploy-azure.md	Deployment guide for Microsoft Azure.
site/content/in-dev/1.0.0/getting-started/deploying-polaris/quickstart-deploy-aws.md	Deployment guide for Amazon Web Services with a noted typo.
site/content/in-dev/1.0.0/deploying-polaris/_index.md	Index page addressing cloud provider deployments.
site/content/in-dev/1.0.0/getting-started/_index.md	Getting started overview page.
site/content/in-dev/1.0.0/generic-table.md	Documentation for Generic Table (Beta) functionality.
site/content/in-dev/1.0.0/evolution.md	Document describing the Polaris evolution strategy and upgrade considerations.
site/content/in-dev/1.0.0/entities.md	Overview of the various entities managed in Polaris.
site/content/in-dev/1.0.0/configuring-polaris-for-production.md	Production configuration guidelines and checklist.
site/content/in-dev/1.0.0/configuration.md	Detailed configuration reference for Polaris (includes a potential typo).
site/content/in-dev/1.0.0/admin-tool.md	Documentation for the Polaris administration tool.
site/content/in-dev/1.0.0/access-control.md	Comprehensive guide on access control and RBAC in Polaris.
site/content/in-dev/1.0.0/_index.md	Overview page for the 1.0.0 documentation set.

Copilot · 2025-06-18T22:47:33Z

site/content/in-dev/1.0.0/getting-started/deploying-polaris/quickstart-deploy-aws.md

+```
+
+## Next Steps
+Congrats, you now have a running instance of1 Polaris! For details on how to use Polaris, check out the [Using Polaris]({{% relref "../using-polaris.md" %}}) page.


There is a typo in the message: 'instance of1 Polaris' should be corrected to 'instance of Polaris'.

Suggested change

Congrats, you now have a running instance of1 Polaris! For details on how to use Polaris, check out the [Using Polaris]({{% relref "../using-polaris.md" %}}) page.

Congrats, you now have a running instance of Polaris! For details on how to use Polaris, check out the [Using Polaris]({{% relref "../using-polaris.md" %}}) page.

Copilot · 2025-06-18T22:47:34Z

site/content/in-dev/1.0.0/configuration.md

+|----------------------------------------------------------------------------------------|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `polaris.persistence.type`                                                             | `relational-jdbc`     | Define the persistence backend used by Polaris (`in-memory`, `relational-jdbc`, `eclipse-link` (deprecated)). See [Configuring Apache Polaris for Production)[{{% ref "configuring-polaris-for-production.md" %}}) | 
+| `polaris.persistence.relational.jdbc.max-retries`                                      | `1`                   | Total number of retries JDBC persistence will attempt on connection resets or serialization failures before giving up.                                                                                             |
+| `polaris.persistence.relational.jdbc.max_duaration_in_ms`                              | `5000 ms`             | Max time interval (ms) since the start of a transaction when retries can be attempted.                                                                                                                             |


The property name 'max_duaration_in_ms' appears to contain a typo. It might be intended to be 'max_duration_in_ms'.

Suggested change

| `polaris.persistence.relational.jdbc.max_duaration_in_ms` | `5000 ms` | Max time interval (ms) since the start of a transaction when retries can be attempted. |

| `polaris.persistence.relational.jdbc.max_duration_in_ms` | `5000 ms` | Max time interval (ms) since the start of a transaction when retries can be attempted. |

copilot did a good job to find typos! We should fix it in both places.

jbonofre

LGTM, thanks !

NB: we should try to use versioned-docs branch. See 237ce0c

flyrain · 2025-06-20T17:55:55Z

NB: we should try to use versioned-docs branch. See 237ce0c

Thanks @jbonofre ! What's the plan of using the branch? How does it work with the current site?

snazy · 2025-06-23T07:52:52Z

These docs will appear in the URL https://polaris.apache.org/in-dev/1.0.0/ instead of https://polaris.apache.org/releases/1.0.0/. IMHO "in-dev" is not appropriate for a release.

flyrain · 2025-06-23T17:11:30Z

These docs will appear in the URL https://polaris.apache.org/in-dev/1.0.0/ instead of https://polaris.apache.org/releases/1.0.0/. IMHO "in-dev" is not appropriate for a release.

That makes sense. Considering the 0.9 doc is also in in-dev, how about refactor it in a follow-up PR? Here is my plan, right after this PR. I will move both 0.9 and 1.0.0 to a new dir releases, and we could also combine the in-dev and unreleased to either unreleased.

snazy · 2025-06-23T17:51:06Z

Why refactor? Just push the versioned docs to the versioned-docs branch and those will automatically be accessible under .../releases/....

jbonofre · 2025-06-23T18:15:43Z

The reason why I pushed in in-dev is because it's 0.9.x (not the release), as an active branch. I'm fine to push only 0.9.0 or release numbers in versioned-docs branch and so in /releases.

flyrain · 2025-06-23T18:23:01Z

The directory name is 0.9.0 and the doc inside are intended for that particular release. At least, any site visitor will consider so. The reason to refactor it is to move 0.9.0 as well, and follow the previous pattern done in the previous release.

jbonofre · 2025-06-23T19:24:50Z

Yes agree. Just explained the initial reason.

snazy · 2025-06-24T07:27:23Z

But why not doing it now right away instead of another PR?

flyrain · 2025-06-25T01:03:18Z

As I said at #1910 (comment). The refactor needs to cover 0.9.0 as well. The current PR is consistent with the previous behavior. I'm actually quite concern that once I made the change you suggest, someone may point out "why are you not follow the convention?". Believe or not, It happens to me a lot.

flyrain · 2025-07-08T23:42:47Z

@snazy moved it to a new dir(releases) as you suggested

snazy

This change causes a serious conflict with both site/bin/checkout-releases.sh and .github/workflows/site.yml.

The "right" way would be:

Have the 1.0.0 docs in the actual release branch's site/content/in-dev/unreleased/ folder
When released, push the files from polaris/main:site/content/in-dev/unreleased/ to polaris/versioned-docs:1.0.0/

Plus there are unrelated changes to the quickstart pages in this PR.

flyrain · 2025-07-10T00:33:51Z

@snazy , thanks for the pointer. Put them in the branch versioned-docs now.

Publish 1.0.0 documents

0836894

github-project-automation bot added this to Basic Kanban Board Jun 18, 2025

github-project-automation bot moved this to PRs In Progress in Basic Kanban Board Jun 18, 2025

flyrain requested review from Copilot and jbonofre June 18, 2025 22:46

Copilot AI reviewed Jun 18, 2025

View reviewed changes

flyrain requested review from dimas-b, eric-maynard, gh-yzou and singhpk234 June 18, 2025 22:49

jbonofre previously approved these changes Jun 20, 2025

View reviewed changes

github-project-automation bot moved this from PRs In Progress to Ready to merge in Basic Kanban Board Jun 20, 2025

Resolve comments

a81c268

flyrain dismissed jbonofre’s stale review via a81c268 July 8, 2025 23:39

Resolve comments

3e3a117

snazy requested changes Jul 9, 2025

View reviewed changes

github-project-automation bot moved this from Ready to merge to PRs In Progress in Basic Kanban Board Jul 9, 2025

flyrain mentioned this pull request Jul 11, 2025

[Site] Simplify the doc directory structure #2033

Merged

flyrain closed this Jul 11, 2025

github-project-automation bot moved this from PRs In Progress to Done in Basic Kanban Board Jul 11, 2025

	Congrats, you now have a running instance of1 Polaris! For details on how to use Polaris, check out the [Using Polaris]({{% relref "../using-polaris.md" %}}) page.
	Congrats, you now have a running instance of Polaris! For details on how to use Polaris, check out the [Using Polaris]({{% relref "../using-polaris.md" %}}) page.

	\| `polaris.persistence.relational.jdbc.max_duaration_in_ms` \| `5000 ms` \| Max time interval (ms) since the start of a transaction when retries can be attempted. \|
	\| `polaris.persistence.relational.jdbc.max_duration_in_ms` \| `5000 ms` \| Max time interval (ms) since the start of a transaction when retries can be attempted. \|

Conversation

flyrain commented Jun 18, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Jun 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 18, 2025

Choose a reason for hiding this comment

Uh oh!

flyrain Jun 18, 2025

Choose a reason for hiding this comment

Uh oh!

jbonofre left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

flyrain commented Jun 20, 2025

Uh oh!

snazy commented Jun 23, 2025

Uh oh!

flyrain commented Jun 23, 2025

Uh oh!

snazy commented Jun 23, 2025

Uh oh!

jbonofre commented Jun 23, 2025

Uh oh!

flyrain commented Jun 23, 2025

Uh oh!

jbonofre commented Jun 23, 2025

Uh oh!

snazy commented Jun 24, 2025

Uh oh!

flyrain commented Jun 25, 2025

Uh oh!

flyrain commented Jul 8, 2025

Uh oh!

snazy left a comment

Choose a reason for hiding this comment

Uh oh!

flyrain commented Jul 10, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jbonofre left a comment •

edited

Loading