docs(vscode): Improve Gradle import tutorial clarity and completeness (#121) #137

arshinsikka · 2025-07-30T16:31:25Z

This PR improves the VS Code tutorial for importing Gradle projects as discussed in issue #121.

Improvements:

✅ Added context on Gradle support in VS Code
✅ Clarified that Gradle is included in Java Extension Pack
✅ Described typical Gradle project file structure
✅ Added workspace trust prompt tip
✅ Included gradle -version tip and JAVA_HOME guidance
✅ Mentioned Gradle Tasks Panel usage
✅ Added a concise troubleshooting section

These improvements follow suggestions by @damithc and @Johnwz123.
Closes #121

arshinsikka · 2025-07-30T16:33:35Z

@damithc @Johnwz123 Thank you for your suggestions on improving the Gradle tutorial. I’ve incorporated the key points we discussed — including clarifications on Gradle support, workspace trust, project structure, JVM configuration, and troubleshooting tips.

Please let me know if there’s anything I may have missed or if further refinements are needed — I’d be happy to make additional improvements!

damithc

Some changes suggested.

damithc · 2025-07-31T13:27:38Z

tutorials/vscImportingGradleProject.md


 This guide will help you import and work with existing Gradle projects in VS Code.

+💡 VS Code offers good Gradle support through extensions, though some manual steps may still be needed for a smooth experience.


@arshinsikka Use icons from font-based icons supported by MarkBind, for a consistent look. The emojis you have used vary appearance based on the browser.

See https://markbind.org/userGuide/formattingContents.html#using-font-awesome-icons for more info. If using fontawesome icons, choose free ones only.

damithc · 2025-07-31T13:31:37Z

tutorials/vscImportingGradleProject.md

+- `src/main/java`
+- `src/test/java`
+
+


This is not specific to VSCode. Hence, best given in https://se-education.org/guides/tutorials/gradle.html rather than here.

This issue not addressed yet.

damithc · 2025-07-31T13:33:15Z

tutorials/vscImportingGradleProject.md

 1. **Navigate to your existing Gradle project** folder
 1. **Click "Select Folder"** to open it as a workspace

+💡 When prompted, click "Yes" to trust the workspace so that Gradle tasks and extensions can run correctly.


To be consistent with other tutorials, use back-ticks when referring to UI elements e.g., Yes instead of "Yes". This might require changes in other places of this page too.

damithc · 2025-07-31T13:34:45Z

tutorials/vscImportingGradleProject.md


 <pic src="images/vscode/vscode_gradle_icon.jpg" width="400" />

+## 🛠️ Troubleshooting


Keep the changes consistent with the rest of the page e.g., other headings don't use emojis

arshinsikka · 2025-08-02T07:58:53Z

Hi @damithc,
Thanks for the helpful suggestions! I’ve made the requested changes:

Replaced emojis with Font Awesome icons or removed them where unnecessary
Updated section headings to avoid emoji usage (e.g., "Troubleshooting")
Used backticks for UI elements like Yes and Select Folder for consistency
Moved the generic Gradle setup tip into a proper tip box linking to the external tutorial
Ensured formatting aligns with other tutorials on the site

Please let me know if there’s anything else to adjust — happy to refine further! 😊

damithc · 2025-08-02T14:09:17Z

tutorials/vscImportingGradleProject.md

+
 <box type="important" seamless>

+### 🗂 Typical Gradle Project Structure


Not fully resolved yet e.g., this heading has an emoji

… Gradle tutorial

arshinsikka · 2025-08-03T11:35:30Z

Hi Prof @damithc,
Thanks again for your feedback!

I've gone ahead and addressed the remaining items:

✅ Removed all emojis (including Font Awesome ones) from headings for consistency
✅ Used backticks for all UI labels like Yes and Select Folder
✅ Finalized the contributors section with my name added

Please let me know if there’s anything else you'd like tweaked — happy to refine further!

damithc

Some comments added.

damithc · 2025-08-03T14:57:21Z

tutorials/vscImportingGradleProject.md

 ## Importing an existing Gradle project

-### Step 1: Open the project folder
+### ### Step 1: Open the Project Folder


This doesn't look right.

damithc · 2025-08-03T14:57:40Z

tutorials/vscImportingGradleProject.md

+- `src/main/java`
+- `src/test/java`
+
+


This issue not addressed yet.

damithc · 2025-08-10T07:52:49Z

@arshinsikka Waiting for you to fix the remaining issues

…section, fix heading, backtick UI labels, convert Gradle view note to info box, drop missing image, minor grammar

arshinsikka · 2025-08-11T10:17:48Z

Hi Prof @damithc — thanks for the nudge! I’ve addressed the remaining items:

Removed the Typical Gradle Project Structure section (linked to the general Gradle tutorial instead, since it’s not VS Code–specific).
Fixed the heading typo (### ### Step 1 → ### Step 1).
Standardized UI labels with backticks where relevant (e.g., Yes, Select Folder…, File → Open Folder…).
Consolidated the Gradle view guidance into a small info box and linked to the official VS Code docs.
Removed the local image reference to avoid a broken asset.
Minor grammar/consistency touch‑ups.

Please let me know if you’d like any further tweaks — happy to adjust!

damithc · 2025-09-06T06:11:09Z

Sorry, it took a while to get to this PR. @arshinsikka it is not advisable for new contributors to send many PRs at once. Maintainers will prioritise other PRs because such multiple PRs from a new contributor means repetitive work e.g., asking to fix the same problem in multiple PRs. It is better to gradually increasing the PR count/size so that you can align your work with the standards of the repo first.

damithc · 2025-09-06T06:11:34Z

@Johnwz123 Any inputs on this?

Johnwz123

Added some comments.

Johnwz123 · 2025-09-07T15:29:42Z

tutorials/vscImportingGradleProject.md

 This guide will help you import and work with existing Gradle projects in VS Code.

+<box type="tip" seamless>
+For general Gradle setup guidance, see <a href="https://se-education.org/guides/tutorials/gradle.html" target="_blank">our Gradle tutorial</a>.


Suggested change

For general Gradle setup guidance, see <a href="https://se-education.org/guides/tutorials/gradle.html" target="_blank">our Gradle tutorial</a>.

For general Gradle setup guidance, see [our Gradle tutorial](https://se-education.org/guides/tutorials/gradle.html).

For consistency, I think we should stick to the Markdown way of formatting links rather than the HTML way.

Johnwz123 · 2025-09-07T15:40:53Z

tutorials/vscImportingGradleProject.md

 1. **Check the status bar** at the bottom for any initialization messages

+<box type="tip" seamless>
+If your project uses Gradle, you should see a `build.gradle` or `build.gradle.kts` in the project root.


I think this would make more sense to be under the "Prerequisites" section instead as a check for users to verify that the Java project is a Gradle project before proceeding with the rest of the tutorial. What do you think?

Johnwz123 · 2025-09-07T15:46:12Z

tutorials/vscImportingGradleProject.md

-**Confirm you can access the Gradle tool window**. After the importing of the project is complete (which could take a few minutes), you will see the Gradle Tab in the VS Code interface (Look for the elephant icon on the left and click it).
+<box type="info" seamless>
+Open the **Gradle** view from the Activity Bar (elephant icon) to browse and run tasks.  
+See: <a href="https://code.visualstudio.com/docs/java/java-build#_gradle-support" target="_blank">VS Code: Java — Build with Gradle</a>.


The fragment identifier (#) for the link doesn't seem to exist when I tried? Also, I think it would be better to not wrap it in an "info" box since I think it is an important step to verify that the setup is successful.

Johnwz123 · 2025-09-07T15:55:12Z

tutorials/vscImportingGradleProject.md

 If the Gradle icon doesn't appear after restarting VS Code, add `"gradle.nestedProjects": true` to your `settings.json` file.
 </box>

-<pic src="images/vscode/vscode_gradle_icon.jpg" width="400" />


Any reason for removing the image?

Johnwz123 · 2025-09-07T15:56:39Z

tutorials/vscImportingGradleProject.md

+Gradle support is included by default in the Java Extension Pack, so no separate Gradle installation is usually required.
 </box>

+<box type="important" seamless>


This seems out of place?

docs(vscode): Improve Gradle import tutorial clarity and completeness (…

4e00170

…se-edu#121)

damithc requested changes Jul 31, 2025

View reviewed changes

docs(vscode): fix formatting and consistency based on review feedback

f724158

damithc reviewed Aug 2, 2025

View reviewed changes

docs(vscode): Remove emojis from headings and finalize formatting for…

2993ef1

… Gradle tutorial

damithc reviewed Aug 3, 2025

View reviewed changes

docs(vscode): address remaining review feedback — remove non‑VS Code …

308a5a5

…section, fix heading, backtick UI labels, convert Gradle view note to info box, drop missing image, minor grammar

Johnwz123 reviewed Sep 7, 2025

View reviewed changes


		This guide will help you import and work with existing Gradle projects in VS Code.

		💡 VS Code offers good Gradle support through extensions, though some manual steps may still be needed for a smooth experience.


		<pic src="images/vscode/vscode_gradle_icon.jpg" width="400" />

		## 🛠️ Troubleshooting


		<box type="important" seamless>

		### 🗂 Typical Gradle Project Structure

	For general Gradle setup guidance, see <a href="https://se-education.org/guides/tutorials/gradle.html" target="_blank">our Gradle tutorial</a>.
	For general Gradle setup guidance, see [our Gradle tutorial](https://se-education.org/guides/tutorials/gradle.html).

docs(vscode): Improve Gradle import tutorial clarity and completeness (#121) #137

Are you sure you want to change the base?

docs(vscode): Improve Gradle import tutorial clarity and completeness (#121) #137

Uh oh!

Conversation

arshinsikka commented Jul 30, 2025

Improvements:

Uh oh!

arshinsikka commented Jul 30, 2025

Uh oh!

damithc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

arshinsikka commented Aug 2, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

arshinsikka commented Aug 3, 2025

Uh oh!

damithc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

damithc commented Aug 10, 2025

Uh oh!

arshinsikka commented Aug 11, 2025

Uh oh!

damithc commented Sep 6, 2025

Uh oh!

damithc commented Sep 6, 2025

Uh oh!

Johnwz123 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants