docs: improve getting started and README documentation#2267

Merged

dimas-b merged 13 commits intoapache:mainfrom

Subham-KRLX:add-binary-distribution-doc

Nov 19, 2025

Contributor

Subham-KRLX commented Aug 5, 2025 •

edited

Loading

This PR improves the Apache Polaris documentation by enhancing the "Getting Started with Binary Distribution" guide and updating the related README file.

These updates include formatting fixes, compliance with Markdown linting standards, added code block language specifiers, and clearer, more concise instructions to improve readability and user experience.

Key changes:
Fixed markdownlint issues such as line length violations and missing code block languages.
Shortened and clarified descriptive text for better comprehension.
Removed duplicate and redundant sections.
Verified proper formatting and rendering via a local Hugo site build.

Closes #1590


          docs: improve getting started and README documentation

f3a8d9d

github-project-automation bot added this to Basic Kanban Board

github-project-automation bot moved this to PRs In Progress in Basic Kanban Board

flyrain reviewed

View reviewed changes

Contributor

flyrain left a comment

Hi @Subham-KRLX, thanks a lot for picking this up. Can we add the binary distribution instruction in this page, https://polaris.apache.org/in-dev/unreleased/getting-started/quickstart/? And we don't need the change in README.md in that case.

adutra reviewed

View reviewed changes

getting-started/getting-started-binary.md Outdated Show resolved Hide resolved

getting-started/getting-started-binary.md Outdated Show resolved Hide resolved

Contributor Author

Subham-KRLX commented Aug 6, 2025

Give me some time; I will fix everything that is necessary.


          Revert changes to getting-started/README.md as per reviewer request

163e595

Contributor Author

Subham-KRLX commented Aug 6, 2025

@flyrain, Could you please specify where exactly to add the binary distribution instructions in the Quickstart page? Should it be a separate section after “Running Polaris as a Standalone Process” including all steps like prerequisites ,download, configuration, start, verify, and stop? Also what title do you prefer for the section? I want to ensure the update aligns perfectly with your expectations before proceeding.

Contributor

flyrain commented Aug 6, 2025

Looking a bit more, I think it makes more sense to have it in this page, https://github.com/apache/polaris/blob/af69d9f9699d8a0cae1b70839e1b5c1bfc9ba511/site/content/in-dev/unreleased/getting-started/_index.md. So that every time, people click "Getting Started", the index page shows up and provide instructions for binary package usage, which probably the fastest way to set up a Polaris server.

One more thing we could add into the index page is the link to this page, https://polaris.apache.org/in-dev/unreleased/getting-started/quickstart/, which shows how to start from the source code.

And we can change the link in this line

polaris/README.md

Line 43 in 04e65af

    
           Click [here](https://polaris.apache.org/in-dev/unreleased/getting-started/install-dependencies/) for the quickstart experience, which will help you set up a Polaris instance locally or on any supported cloud provider.

to the index page.

Subham-KRLX and others added 2 commits

August 7, 2025 07:50


          Consolidate binary setup in Getting Started index, update README quic…

48da122

…kstart link, update quickstart.md and remove redundant binary doc


          Update quickstart.md

83cbb87

removing blank spaces.

Subham-KRLX requested a review from flyrain

August 7, 2025 05:25

flyrain previously approved these changes

View reviewed changes

Contributor

flyrain left a comment

Thanks for the update. LGTM.

site/content/in-dev/unreleased/getting-started/_index.md Outdated Show resolved Hide resolved

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


          Update _index.md

456997f

updating the link.

Subham-KRLX dismissed flyrain’s stale review via

456997f

August 8, 2025 01:06

Subham-KRLX requested review from adutra and flyrain

August 8, 2025 01:07

flyrain reviewed

View reviewed changes

site/content/in-dev/unreleased/getting-started/_index.md Outdated Show resolved Hide resolved

eric-maynard reviewed

View reviewed changes

README.md Show resolved Hide resolved


          Update _index.md

81b9ce5

removing the bash commands which are not in use.

Subham-KRLX requested review from eric-maynard and flyrain

August 8, 2025 17:16

Contributor Author

Subham-KRLX commented Aug 8, 2025

I think it's good to go now.

flyrain reviewed

View reviewed changes

site/content/in-dev/unreleased/getting-started/_index.md Outdated Show resolved Hide resolved

eric-maynard reviewed

View reviewed changes

site/content/in-dev/unreleased/getting-started/_index.md Outdated Show resolved Hide resolved

eric-maynard reviewed

View reviewed changes

site/content/in-dev/unreleased/getting-started/_index.md Outdated Show resolved Hide resolved

eric-maynard reviewed

View reviewed changes

site/content/in-dev/unreleased/getting-started/_index.md Outdated Show resolved Hide resolved

eric-maynard reviewed

View reviewed changes

site/content/in-dev/unreleased/getting-started/_index.md Outdated Show resolved Hide resolved

eric-maynard reviewed

View reviewed changes

site/content/in-dev/unreleased/getting-started/_index.md Outdated Show resolved Hide resolved

Contributor

flyrain commented Aug 11, 2025

@flyrain,My local build fails in the polaris-admin test phase with the message: “The Agroal dependency is present but no JDBC datasources have been defined.” Since my PR only updates documentation this seems unrelated to my changes. Is this a test environment issue or do I need to configure a test datasource? Please advise.

Reopen it to trigger the CI

dimas-b reviewed

View reviewed changes

site/content/in-dev/unreleased/getting-started/_index.md Outdated Show resolved Hide resolved

Subham-KRLX requested a review from dimas-b

August 12, 2025 02:15

Contributor Author

Subham-KRLX commented Aug 16, 2025

If this PR is fixed please feel free to merge it. If not kindly provide the corrections I need to make so I can start working on the issue assigned to me and raise a PR regarding that issue.

Subham-KRLX requested a review from snazy

August 30, 2025 07:07

Subham-KRLX marked this pull request as draft

November 12, 2025 09:33


          Merge upstream/main and resolve conflicts

d40b4a7

Subham-KRLX marked this pull request as ready for review

November 15, 2025 04:11

flyrain reviewed

View reviewed changes

site/content/in-dev/unreleased/getting-started/_index.md Outdated Show resolved Hide resolved

flyrain reviewed

View reviewed changes

site/content/in-dev/unreleased/getting-started/_index.md Outdated Show resolved Hide resolved

flyrain reviewed

View reviewed changes

site/content/in-dev/unreleased/getting-started/_index.md Outdated Show resolved Hide resolved


          Fix binary distribution commands per reviewer feedback

6219a5c

flyrain reviewed

View reviewed changes

Contributor

flyrain left a comment

Thanks @Subham-KRLX for working on it. Left some comments.

site/content/in-dev/unreleased/getting-started/_index.md Outdated

+              java -version
+              ```
+              ---

Contributor

flyrain Nov 17, 2025

Nit: the separator may not be quite helpful for a small section like this. Could we remove all of them?

site/content/in-dev/unreleased/getting-started/_index.md Outdated

Comment on lines 55 to 57

		## Step 2: Extract the Archive

		Extract the downloaded tar.gz file to your desired directory:

Contributor

flyrain Nov 17, 2025

please remove this step as step 1 extract it already.

site/content/in-dev/unreleased/getting-started/_index.md Outdated Show resolved Hide resolved

site/content/in-dev/unreleased/getting-started/_index.md Outdated

+              Extract the downloaded tar.gz file to your desired directory:
+              ```bash
+              cd apache-polaris-1.0.0-incubating-bin

Contributor

flyrain Nov 17, 2025

we could move this to next step configure Polaris

site/content/in-dev/unreleased/getting-started/_index.md Outdated

+              Configure Polaris using environment variables or system properties. For example:
+              ```bash
+              export POLARIS_JAVA_OPTS="-Dpolaris.storage.backend=local -Dpolaris.storage.local.path=/data/polaris"

Contributor

flyrain Nov 17, 2025

these two options don't exist

site/content/in-dev/unreleased/getting-started/_index.md Outdated

+              Open your browser and navigate to:
+              ```bash
+              curl http://localhost:8181/api/catalog/v1/health

Contributor

flyrain Nov 17, 2025

I think the path is wrong.

site/content/in-dev/unreleased/getting-started/_index.md Outdated


		## Additional Resources

		- See the [official Apache Polaris documentation](https://polaris.apache.org/docs/) for comprehensive information on configuration, deployment, and usage.

Contributor

flyrain Nov 17, 2025

we may not need to mention it, as people visiting this page are already here.

site/content/in-dev/unreleased/getting-started/_index.md Outdated

+              ## Additional Resources
+              - See the [official Apache Polaris documentation](https://polaris.apache.org/docs/) for comprehensive information on configuration, deployment, and usage.
+              - Use `bin/admin` in the binary distribution for administrative and maintenance tasks (e.g., `bin/admin bootstrap`, `bin/admin purge`).

Contributor

flyrain Nov 17, 2025

I'd suggest to take a look at https://github.com/apache/polaris/blob/main/runtime/distribution/README.md for more context.

Subham-KRLX force-pushed the add-binary-distribution-doc branch from 6219a5c to 1e478e9 Compare

November 17, 2025 05:29


          Fix binary distribution commands per reviewer feedback

742e68f

Subham-KRLX force-pushed the add-binary-distribution-doc branch from 1e478e9 to 742e68f Compare

November 17, 2025 05:29


          Remove comments from code blocks

f381a4e

dimas-b reviewed

View reviewed changes

Contributor

dimas-b left a comment

Thanks for resuming work on this, @Subham-KRLX !

site/content/in-dev/unreleased/getting-started/_index.md Outdated

+              ```
-              ### Getting Help
+              ## Step 1: Download and Extract the Binary Distribution

Contributor

dimas-b Nov 17, 2025

We have this (based on tar) and https://polaris.apache.org/in-dev/unreleased/getting-started/quick-start/ (based on docker). Would it make sense to move this section into a sub-page parallel to the docker-compose example?

site/content/in-dev/unreleased/getting-started/_index.md Outdated Show resolved Hide resolved


          Address reviewer feedback on binary distribution docs

1fac34c

dimas-b reviewed

View reviewed changes

site/content/in-dev/unreleased/getting-started/_index.md Show resolved Hide resolved


          Refactor getting started docs

9a8ca15

Contributor Author

Subham-KRLX commented Nov 18, 2025

Hey everyone thanks so much for the detailed feedback. I’ve moved the tar based instructions over to a
new binary-distribution.md page (which now runs in parallel with quick-start.md). also simplified
getting-started/_index.md into a clean landing page that directs people to both options.

With this update:

The outdated config snippets and health-checks are removed from the index
The binary guide stays focused and concise
The structure aligns with the suggestions from the reviewers

flyrain approved these changes

View reviewed changes

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

dimas-b approved these changes

View reviewed changes

Contributor

dimas-b left a comment

Thanks for working on this, @Subham-KRLX !

Contributor

dimas-b commented Nov 19, 2025

This PR had a lot of work and feedback. I'm merging now. If there are additional comments, follow-up doc changes are always welcome.

dimas-b enabled auto-merge (squash)

November 19, 2025 16:19

dimas-b merged commit d75fa71 into apache:main

15 checks passed

github-project-automation bot moved this from Ready to merge to Done in Basic Kanban Board

snazy added a commit to snazy/polaris that referenced this pull request


          Dremio merge 2025 11 24 09 20 (apache#167)

32097e7

* Docs: update Helm Chart page to show usage without cloning Polaris github repo (apache#2939)

* Docs: update Helm Chart page to show usage without cloning Polaris github repo

* Apply suggestions from code review

* Add separate flows in Helm Chart doc for installing released chart and images vs building from source

---------

Co-authored-by: Alexandre Dutra <adutra@apache.org>

* docs: improve getting started and README documentation (apache#2267)

* The outdated config snippets and health-checks are removed from the index

* The binary guide stays focused and concise

* Update changelog with missing 1.3.0 features (apache#3087)

* Update registry.access.redhat.com/ubi9/openjdk-21-runtime Docker tag to v1.23-6.1763034977 (apache#3092)

* Update docker.io/jaegertracing/all-in-one Docker tag to v1.75.0 (apache#3093)

* feat: Make generate_clients.py windows compatible (apache#3084)

* Make generate_clients.py windows compatible

* Updated CHANGELOG.md

* PRs: Remove markdown-links-check from required checks (apache#3102)

The "Check Markdown links" workflow is known to produce false failures, leading to apache#3097.

This change is intended to unblock PRs due to these false failures.

* Update dependency com.diffplug.spotless:spotless-plugin-gradle to v8.1.0 (apache#3083)

* Update dependency com.diffplug.spotless:spotless-plugin-gradle to v8.1.0

* spotlessApply

---------

Co-authored-by: Robert Stupp <snazy@snazy.de>

* chore(deps): update gradle to v9.2.1 (apache#3069)

* chore(deps): update gradle to v9.2.1

* Fix Grale wrapper SHA

---------

Co-authored-by: Robert Stupp <snazy@snazy.de>

* chore(deps): update mongo docker tag to v8.2.2 (apache#3100)

* chore(deps): update docker.io/mongo docker tag to v8.2.2 (apache#3099)

* Source-tarball - eliminate git-gzip risk (apache#3075)

Details in the `git archive` chapter in https://reproducible-builds.org/docs/archives/

* NoSQL: Allow `null` IndexKey (de)serialization (apache#3076)

This change adopts the implementation to the API specification.

* PRs: Re-add markdown-links-check step (apache#3103)

The step was disabled in apache#3102 to pass CI and enable merging.

* NoSQL: Add maintenance implementation (apache#3077)

* Inject DefaultFileIOFactory in tests (apache#3043)

* Inject DefaultFileIOFactory in tests

also simplify `TaskFileIOSupplier` usage in tests, which allows removal
of `TestFileIOFactory`.

* Update Quarkus Platform and Group to v3.29.4 (apache#3094)

* Site: Replace feather logo (apache#3101)

The ASF has a new logo, a leaf. There is sadly no free icon that matches the new logo, so replacing the feather-ASF with "The ASF" in the top-bar navigation.

* Update actions/checkout action to v6 (apache#3106)

* Core: resolveAll() must be called before reading resolution results (apache#3064)

* Site: Added GCS related Bucket Properties for vending credentials. (apache#3066)

* Publish/pom: don't include test-fixtures dependencies as runtime (apache#3085)

The list of dependencies in pom's includes the api/runtime elements of the test-fixtures, which is not what should be published, as it "pulls up" deps like junit, mockito and assertj as Maven runtime scope dependencies.
This change fixes this.

* Increase javadoc visibility in `persistence/nosql/persistence/cdi/weld` (apache#3110)

This is to fix javadoc error: `No public or protected classes found to document`

* Disable cloud storage tests that would use @tempdir (apache#3095)

Disable tests from ViewCatalogTests for cloud storage integration tests
(S3, ADLS, GCS) that would otherwise use @tempdir. Since @tempdir internally
uses Paths.get, it cannot point to cloud storage paths. These tests remain
enabled for file-based integration tests.

* Remove 'beta' label for Generic Table (apache#3096)

* remove beta label

* address comments for change log

---------

Co-authored-by: Pierre Laporte <pierre@pingtimeout.fr>

* Update dependency jupyterlab to v4.5.0 (apache#3074)

* chore: Fix md link check in GH action (apache#3128)

* Fix md link check in GH action

* Fix md link check in GH action

* Update dependency pre-commit to v4.5.0 (apache#3123)

* Update dependency software.amazon.awssdk:bom to v2.39.2 (apache#3127)

* NoSQL: authZ API, SPI, impl and store (apache#3078)

NoSQL base functionality for ACLs

* NoSQL: Quarkus distributed cache invalidation (apache#3105)

Adds support for distributed NoSQL cache invalidation leveraging Quarkus.

* NoSQL: adjustments / merge fixes

* Last merged commit e124348

---------

Co-authored-by: Oleg Soloviov <40199597+olsoloviov@users.noreply.github.com>
Co-authored-by: Alexandre Dutra <adutra@apache.org>
Co-authored-by: Subham <subham.sangwan@adypu.edu.in>
Co-authored-by: Pierre Laporte <pierre@pingtimeout.fr>
Co-authored-by: Mend Renovate <bot@renovateapp.com>
Co-authored-by: Yong Zheng <yongzheng0809@gmail.com>
Co-authored-by: Christopher Lambert <xn137@gmx.de>
Co-authored-by: Yufei Gu <yufei@apache.org>
Co-authored-by: Saksham Ratra <sakshamratra.0106@gmail.com>
Co-authored-by: Dmitri Bourlatchkov <dmitri.bourlatchkov@gmail.com>
Co-authored-by: Tamas Mate <50709850+tmater@users.noreply.github.com>
Co-authored-by: Yun Zou <yunzou.colostate@gmail.com>

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet