Skip to content

docs: update IntelliJ import instructions in building docs - #6857

Open
gtkrish85 wants to merge 2 commits into
apache:masterfrom
gtkrish85:fix-6285-intellij-docs
Open

gtkrish85 wants to merge 2 commits into
apache:masterfrom
gtkrish85:fix-6285-intellij-docs

Conversation

@gtkrish85

@gtkrish85 gtkrish85 commented Nov 15, 2026 •

Copy link
Copy Markdown

Description

Fixes #6285. Updates the IntelliJ IDEA import instructions in xdocs/building.xml: removes steps 2–5, which describe dialogs that no longer exist in current IntelliJ versions, and notes that IntelliJ imports the Gradle project automatically once you open build.gradle.kts.

Motivation and Context

The current instructions cost new contributors time — the issue reporter lost about an hour following steps that don't exist anymore. This brings the docs in line with how current IntelliJ versions actually import Gradle projects.

How Has This Been Tested?

  • Verified the edited xdocs/building.xml is well-formed XML.
  • Confirmed the diff against master touches only the IntelliJ import list (4 stale steps removed, 1 line added).
  • No code changed, so no build or unit tests apply — docs-only change.

Screenshots (if appropriate):

Not applicable — docs-only change, no UI affected.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)

Checklist:

  • My code follows the code style of this project.
  • I have updated the documentation accordingly.

@gtkrish85 gtkrish85 changed the title Fix #6285: Update IntelliJ import instructions in building docs docs: update IntelliJ import instructions in building docs Nov 15, 2026
@gtkrish85
gtkrish85 marked this pull request as ready for review November 15, 2026 15:09
@gtkrish85

Copy link
Copy Markdown
Author

Hi @vlsi — gentle nudge, would you mind taking a look at this small docs fix when you have a moment? It updates the IntelliJ import instructions in xdocs/building.xml (fixes #6285). Happy to adjust anything. Thanks!

@milamberspace milamberspace 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.

Thanks for picking this up, the removed steps indeed no longer exist in current IntelliJ IDEA versions, and the change is well scoped.

Requested change

  • CONTRIBUTING.md (section IntelliJ IDEA, lines 39-43) contains exactly the same outdated steps (Create separate module per source set, Use default gradle wrapper, File already exists, Delete Existing Project and Import). Many new contributors land there first, so after this PR the two documents would contradict each other. Could you apply the same update there?

Suggestions (non-blocking)

  • "You require IntelliJ 2018.3.1 or newer" (building.xml:54 and CONTRIBUTING.md:37) is misleading as well: the build needs JDK 17 and a recent Gradle, which a 2018 IntelliJ cannot handle. Consider dropping the version or pointing to a recent release.
  • The most common pitfall nowadays is the Gradle JVM: mentioning that Settings → Build, Execution, Deployment → Build Tools → Gradle → Gradle JVM must point to JDK 17+ would probably help more than "just wait".

Comment thread xdocs/building.xml Outdated
<li>Make sure "Use default gradle wrapper" is selected</li>
<li>In the "File already exists" dialogue, choose "Yes" to overwrite</li>
<li>In the "Open Project" dialogue, choose "Delete Existing Project and Import"</li>
<li>IntelliJ IDEA will import the Gradle project automatically — just wait for the Gradle sync to finish</li>

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.

Small wording suggestion (no other page in xdocs uses an em dash, and "just" can be dropped):

Suggested change
<li>IntelliJ IDEA will import the Gradle project automatically — just wait for the Gradle sync to finish</li>
<li>IntelliJ IDEA imports the Gradle project automatically; wait for the Gradle sync to finish</li>
<li>If the sync fails, make sure the Gradle JVM (Settings, Build Tools, Gradle) points to JDK 17 or newer</li>

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Misleading IntelliJ project import

2 participants