Skip to content

Commit 0669f05

Browse files
micronaut-buildmicronaut-build
committed
Update common files
1 parent 539eaed commit 0669f05

File tree

10 files changed

+257
-22
lines changed

10 files changed

+257
-22
lines changed

‎.clineignore‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# .clineignore - Cline AI ignore file for Micronaut projects
2+
# This file tells Cline which files/directories to ignore for code intelligence and automation
3+
4+
# === Build outputs ===
5+
build/
6+
*/build/
7+
!build/docs/
8+
!build/docs/**
9+
10+
# === Dependency/Cache directories ===
11+
.gradle/
12+
*/.gradle/
13+
14+
# === IDE/Editor/OS Metadata ===
15+
.vscode/
16+
.idea/
17+
.DS_Store
18+
*.swp
19+
*.swo
20+
*.bak
21+
*.tmp
22+
*.orig
23+
24+
# === Tool-specific/Config artifacts ===
25+
*.log
26+
27+
# === Gradle Wrappers/Binaries ===
28+
gradlew
29+
gradlew.bat

‎.clinerules/coding.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
---
2+
description: Micronaut Development Guide
3+
author: Cédric Champeau
4+
version: 1.0
5+
globs: ["**/*.java", "**/*.kts", "**/*.xml"]
6+
---
7+
8+
# Micronaut Project Development Guide
9+
10+
## Project Overview
11+
12+
This project is a Micronaut module which is part of the Micronaut Framework, a modern, JVM-based, full-stack framework for building modular, easily testable microservice and serverless applications.
13+
14+
The description of what this project is doing can be found in the `gradle.properties` file under the `projectDesc` key.
15+
16+
This repository does not represent an actual application; its modules are designed to be used as dependencies by applications.
17+
The root project MUST NOT contain any code: it is a parent project which coordinates the build and supplies documentation.
18+
19+
⚠️ CRITICAL: DO NOT USE attempt_completion BEFORE TESTING ⚠️
20+
21+
## Command Conventions
22+
23+
- You MUST run all Gradle commands (except testing ones) with the quiet option to reduce output:
24+
- Do NOT use: `--stacktrace`, `--info` (excessive output will not fit the context)
25+
- You MUST run all Gradle testing commands without the `-q` option, since that will suppress the output result of each test.
26+
- Gradle project names are prefixed with `micronaut-`. For example, directory `mylib` maps to Gradle project `:micronaut-mylib`.
27+
- You MUST run Gradle with the Gradle wrapper: `./gradlew`.
28+
- Gradle project names prefixed with `test-` or `test-suite` are not intended for users: they are functional tests of the project
29+
30+
## Main Development Tasks:
31+
32+
- Compile (module): `./gradlew -q :<module>:compileTestJava`
33+
- Test (module): `./gradlew :<module>:test`
34+
- Checkstyle (aggregate task): `./gradlew -q cM`
35+
- Note: `cM` is the canonical Checkstyle runner defined in build logic to validate Checkstyle across the codebase.
36+
- Note: you MUST NOT introduce new warnings. You SHOULD fix warnings in code that you have modified.
37+
- Spotless (check license headers/format): `./gradlew -q spotlessCheck`
38+
- Spotless (auto-fix formatting/headers): `./gradlew -q spotlessApply` (MUST be used to fix violations found by `spotlessCheck`)
39+
40+
## Code style
41+
42+
You SHOULD prefer modern Java idioms: records, pattern matching, sealed interfaces/classes, `var` for local variables.
43+
You MUST NOT use fully qualified class names unless there is a conflict between 2 class names in different packages.
44+
You MUST annotate the code with nullability annotations (`io.micronaut.core.annotation.Nullable`, `io.micronaut.core.annotation.NonNull`).
45+
46+
## Binary compatibility
47+
48+
Micronaut projects are intended to be used in consumer applications and therefore follow semantic versioning. As a consequence:
49+
- You MUST NOT break any public facing API without explicit consent
50+
- You SHOULD run the `./gradlew japiCmp` task to get a report about binary breaking changes
51+
- You SHOULD reduce the visibility of members for non user-facing APIs.
52+
- You MUST annotate non-user facing APIs with `@io.micronaut.core.annotation.Internal`
53+
54+
## Implementation Workflow (Required Checklist)
55+
56+
You MUST follow this sequence after editing source files:
57+
58+
1) Compile affected modules
59+
- `./gradlew -q :<module>:compileTestJava :<module>:compileTestGroovy`
60+
61+
2) Run targeted tests first (fast feedback)
62+
- `./gradlew :<module>:test --tests 'pkg.ClassTest'`
63+
- `./gradlew :<module>:test --tests 'pkg.ClassTest.method'` (optional)
64+
65+
3) Run full tests for all affected modules
66+
- `./gradlew :<module>:test`
67+
68+
4) Static checks
69+
- Checkstyle: `./gradlew -q cM`
70+
71+
5) (Optional) If, and only if you have created new files, you SHOULD run
72+
- Spotless check: `./gradlew -q spotlessCheck`
73+
- If Spotless fails: `./gradlew -q spotlessApply` then re-run `spotlessCheck`
74+
- You MUST NOT add new license headers on existing files: only focus on files you have added
75+
76+
6) Verify a clean working tree
77+
- You SHOULD ensure no unrelated changes are pending before proposing changes.
78+
- Use `git_status` to verify the working tree:
79+
```xml
80+
<use_mcp_tool>
81+
<server_name>mcp-server-git</server_name>
82+
<tool_name>git_status</tool_name>
83+
<arguments>
84+
{
85+
"repo_path": "/home/cchampeau/DEV/PROJECTS/micronaut/micronaut-langchain4j" // adjust absolute path if necessary
86+
}
87+
</arguments>
88+
</use_mcp_tool>
89+
```
90+
91+
## Documentation Requirements
92+
93+
- You MUST update documentation when necessary, following the project’s documentation rules in `.clinerules/docs.md`.
94+
- Before writing code, you SHOULD analyze relevant code files to get full context, then implement changes with minimal surface area.
95+
- You SHOULD list assumptions and uncertainties that need clarification before completing a task.
96+
- You SHOULD check project configuration/build files before proposing structural or dependency changes.
97+
98+
## Context7 Usage (Documentation and Examples)
99+
100+
You MUST use Context7 to get up-to-date, version-specific documentation and code examples for frameworks and libraries.
101+
102+
Preferred library IDs:
103+
- Micronaut main docs: `/websites/micronaut_io`
104+
- Micronaut Test: `/websites/micronaut-projects_github_io_micronaut-test`
105+
- Micronaut Oracle Cloud: `/websites/micronaut-projects_github_io_micronaut-oracle-cloud`
106+
- OpenRewrite: `/openrewrite/rewrite-docs`
107+
108+
Example (fetch docs for a topic):
109+
```xml
110+
<use_mcp_tool>
111+
<server_name>context7-mcp</server_name>
112+
<tool_name>get-library-docs</tool_name>
113+
<arguments>
114+
{
115+
"context7CompatibleLibraryID": "/openrewrite/rewrite-docs",
116+
"topic": "JavaIsoVisitor"
117+
}
118+
</arguments>
119+
</use_mcp_tool>
120+
```
121+
122+
For other libraries, you MUST resolve the library ID first:
123+
```xml
124+
<use_mcp_tool>
125+
<server_name>context7-mcp</server_name>
126+
<tool_name>resolve-library-id</tool_name>
127+
<arguments>
128+
{
129+
"libraryName": "Mockito"
130+
}
131+
</arguments>
132+
</use_mcp_tool>
133+
```
134+
135+
## Dependency Management (Version Catalogs)
136+
137+
- Main dependencies are managed in the Gradle version catalog at `gradle/libs.versions.toml`.
138+
- You MUST use catalogs when adding dependencies (avoid hard-coded coordinates/versions in module builds).
139+
140+
Adding a new dependency (steps):
141+
1) Choose or add the version in the appropriate catalog (`libs.versions.toml`).
142+
2) Add an alias under the relevant section (e.g., `libraries`).
143+
3) Reference the alias from a module’s `build.gradle.kts`, for example:
144+
- `implementation(libs.some.library)`
145+
- `testImplementation(testlibs.some.junit)`
146+
4) Do NOT hardcode versions in module build files; use the catalog entries.
147+
148+
You SHOULD choose the appropriate scope depending on the use of the library:
149+
- `api` for dependencies which appear in public signatures or the API of a module
150+
- `implementation` for dependencies which are implementation details, only used in the method bodies for example
151+
- `compileOnly` for dependencies which are only required at build time but not at runtime
152+
- `runtimeOnly` for dependencies which are only required at run time and not at compile time
153+
154+
## Build logic
155+
156+
Micronaut projects follow Gradle best practices, in particular usage of convention plugins.
157+
Convention plugins live under the `buildSrc` directory.
158+
159+
You MUST NOT add custom build logic directly in `build.gradle(.kts)` files.
160+
You MUST implement build logic as part of convention plugins.
161+
You SHOULD avoid build logic code duplication by moving common build logic into custom convention plugins.
162+
You SHOULD try to prefer composition of convention plugins.
163+
164+
## Key Requirements
165+
166+
You MUST confirm all of the following BEFORE using `attempt_completion`:
167+
168+
- Changes compile successfully (affected modules)
169+
- Targeted tests pass
170+
- Full tests for affected modules pass
171+
- Checkstyle (`cM`) passes
172+
- Spotless (`spotlessCheck`) passes (apply fixes if needed)
173+
- Documentation updated when necessary
174+
- Working tree is clean (no unrelated diffs)
175+
176+
If ANY item is “no”, you MUST NOT use `attempt_completion`.

‎.clinerules/docs.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
## Brief overview
2+
- Documentation for the Micronaut modules is primarily written in Asciidoc format, focusing on user guides, API references, and integration examples. The documentation emphasizes clarity, completeness, and practical examples to help developers integrate Micronaut modules effectively. Insights from the codebase show a focus on modular documentation aligned with subprojects, including setup instructions, usage examples, and troubleshooting tips.
3+
- All the files are within `src/main/docs/guide`. In that directory, there is a `toc.yml` file that is used to generate the table of contents and decide which `.adoc` files are to be included.
4+
5+
## Development workflow
6+
- Write documentation in Asciidoc: Place source files in the appropriate `src/main/docs` directory.
7+
- Build and assemble the documentation guide: Use `./gradlew docs` from the root directory to generate HTML documentation. Since the output of this task may be huge, ignore the output and check the last process exit code to tell if it works. Otherwise, ask the user. If it works, verify the output for formatting and content accuracy.
8+
- Once assembled, the guide will be at `build/docs/`.
9+
- Include examples: Create and reference code examples from the doc-examples/ directory, ensuring they are testable and up-to-date with the latest service versions.
10+
- Test documentation: Run builds regularly and check for broken links or outdated information. Integrate doc checks into CI pipelines using Gradle tasks.
11+
- Review and update: Conduct peer reviews for new documentation or changes, ensuring alignment with coding standards and project updates.
12+
13+
## Documentation best practices
14+
- Follow Asciidoc conventions: Use consistent headings, lists, code blocks, and admonitions (e.g., NOTE, TIP, WARNING) for better readability.
15+
- Provide comprehensive coverage: Include installation instructions, configuration details, usage examples, error handling, and performance tips for each service.
16+
- Use practical examples: Incorporate runnable code snippets from doc-examples/ to demonstrate real-world usage, with clear explanations and expected outputs.
17+
- Ensure accessibility: Use descriptive alt text for images, maintain logical structure, and avoid jargon without explanations.
18+
- Version control: Document version-specific changes and maintain backward compatibility notes.
19+
- Security and best practices: Highlight secure usage patterns, such as proper authentication and data handling.
20+
21+
## Project context
22+
- Focus on Micronaut-specific integration that this project is providing, emphasizing GraalVM compatibility, annotation-driven configurations, and modular design.
23+
- Prioritize user-centric content: Guides should facilitate quick starts, advanced customizations, and troubleshooting for developers building Micronaut applications.
24+
- Align with coding guidelines: Documentation should complement code by explaining architectural decisions, such as the use of factories, interceptors, and annotation processors.

‎.github/workflows/central-sync.yml‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,15 +15,17 @@ jobs:
1515
runs-on: ubuntu-latest
1616
steps:
1717
- name: Checkout repository
18-
uses: actions/checkout@v4
18+
uses: actions/checkout@v5
1919
with:
2020
ref: v${{ github.event.inputs.release_version }}
21-
- uses: gradle/wrapper-validation-action@v3
21+
- uses: gradle/actions/wrapper-validation@v4
2222
- name: Set up JDK
23-
uses: actions/setup-java@v4
23+
uses: actions/setup-java@v5
2424
with:
2525
distribution: 'temurin'
26-
java-version: '17'
26+
java-version: |
27+
17
28+
21
2729
- name: Publish to Sonatype OSSRH
2830
env:
2931
SONATYPE_USERNAME: ${{ secrets.SONATYPE_USERNAME }}

‎.github/workflows/graalvm-dev.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ jobs:
1818
outputs:
1919
matrix: ${{ steps.build-matrix.outputs.matrix }}
2020
steps:
21-
- uses: actions/checkout@v4
21+
- uses: actions/checkout@v5
2222
- name: Build Matrix
2323
uses: micronaut-projects/github-actions/graalvm/build-matrix@master
2424
id: build-matrix
@@ -42,7 +42,7 @@ jobs:
4242
DEVELOCITY_CACHE_USERNAME: ${{ secrets.GRADLE_ENTERPRISE_CACHE_USERNAME }}
4343
DEVELOCITY_CACHE_PASSWORD: ${{ secrets.GRADLE_ENTERPRISE_CACHE_PASSWORD }}
4444
steps:
45-
- uses: actions/checkout@v4
45+
- uses: actions/checkout@v5
4646
- name: Pre-Build Steps
4747
uses: micronaut-projects/github-actions/graalvm/pre-build@master
4848
id: pre-build

‎.github/workflows/graalvm-latest.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ jobs:
2424
outputs:
2525
matrix: ${{ steps.build-matrix.outputs.matrix }}
2626
steps:
27-
- uses: actions/checkout@v4
27+
- uses: actions/checkout@v5
2828
- name: Build Matrix
2929
uses: micronaut-projects/github-actions/graalvm/build-matrix@master
3030
id: build-matrix
@@ -42,7 +42,7 @@ jobs:
4242
DEVELOCITY_CACHE_USERNAME: ${{ secrets.GRADLE_ENTERPRISE_CACHE_USERNAME }}
4343
DEVELOCITY_CACHE_PASSWORD: ${{ secrets.GRADLE_ENTERPRISE_CACHE_PASSWORD }}
4444
steps:
45-
- uses: actions/checkout@v4
45+
- uses: actions/checkout@v5
4646
- name: Pre-Build Steps
4747
uses: micronaut-projects/github-actions/graalvm/pre-build@master
4848
id: pre-build

‎.github/workflows/gradle.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -42,19 +42,19 @@ jobs:
4242
df -h
4343
4444
- name: "📥 Checkout repository"
45-
uses: actions/checkout@v4
45+
uses: actions/checkout@v5
4646
with:
4747
fetch-depth: 0
4848

4949
- name: "🔧 Setup GraalVM CE"
50-
uses: graalvm/[email protected].3
50+
uses: graalvm/[email protected].6
5151
with:
5252
distribution: 'graalvm'
5353
java-version: ${{ matrix.java }}
5454
github-token: ${{ secrets.GITHUB_TOKEN }}
5555

5656
- name: "🔧 Setup Gradle"
57-
uses: gradle/[email protected]
57+
uses: gradle/actions/setup-gradle@v4
5858

5959
- name: "❓ Optional setup step"
6060
run: |

‎.github/workflows/publish-snapshot.yml‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,18 +10,20 @@ jobs:
1010
if: github.repository != 'micronaut-projects/micronaut-project-template'
1111
runs-on: ubuntu-latest
1212
steps:
13-
- uses: actions/checkout@v4
13+
- uses: actions/checkout@v5
1414
- uses: actions/cache@v4
1515
with:
1616
path: ~/.gradle/caches
1717
key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle') }}
1818
restore-keys: |
1919
${{ runner.os }}-gradle-
2020
- name: Set up JDK
21-
uses: actions/setup-java@v4
21+
uses: actions/setup-java@v5
2222
with:
2323
distribution: 'temurin'
24-
java-version: '17'
24+
java-version: |
25+
17
26+
21
2527
- name: Publish to Sonatype Snapshots
2628
if: success()
2729
env:

‎.github/workflows/release.yml‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -14,15 +14,17 @@ jobs:
1414
runs-on: ubuntu-latest
1515
steps:
1616
- name: Checkout repository
17-
uses: actions/checkout@v4
17+
uses: actions/checkout@v5
1818
with:
1919
token: ${{ secrets.GH_TOKEN }}
20-
- uses: gradle/wrapper-validation-action@v3
20+
- uses: gradle/actions/wrapper-validation@v4
2121
- name: Set up JDK
22-
uses: actions/setup-java@v4
22+
uses: actions/setup-java@v5
2323
with:
2424
distribution: 'temurin'
25-
java-version: '17'
25+
java-version: |
26+
17
27+
21
2628
- name: Set the current release version
2729
id: release_version
2830
run: echo "release_version=${GITHUB_REF:11}" >> $GITHUB_OUTPUT
@@ -115,7 +117,7 @@ jobs:
115117
artifacts-sha256: ${{ steps.set-hash.outputs.artifacts-sha256 }}
116118
steps:
117119
- name: Download artifacts-sha256
118-
uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
120+
uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
119121
with:
120122
name: artifacts-sha256
121123
# The SLSA provenance generator expects the hash digest of artifacts to be passed as a job
@@ -146,9 +148,9 @@ jobs:
146148
if: startsWith(github.ref, 'refs/tags/')
147149
steps:
148150
- name: Checkout repository
149-
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
151+
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
150152
- name: Download artifacts
151-
uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
153+
uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
152154
with:
153155
name: gradle-build-outputs
154156
path: build/repo

‎gradle/wrapper/gradle-wrapper.properties‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
distributionBase=GRADLE_USER_HOME
22
distributionPath=wrapper/dists
3-
distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.2-bin.zip
3+
distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-bin.zip
44
networkTimeout=10000
55
validateDistributionUrl=true
66
zipStoreBase=GRADLE_USER_HOME

0 commit comments

Comments
 (0)