Skip to content

Commit 39b612a

Browse files
ShreckYeShreckYe
authored
Merge pull request #28 from huanshankeji/copilot/fix-abca91ab-9bdd-4c62-a01b-8cdfebbf7764
Add .github/copilot-instructions.md to onboard Copilot coding agents
2 parents 94947b3 + 77db21b commit 39b612a

1 file changed

Lines changed: 193 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# Copilot Instructions for gradle-common
2+
3+
## Repository Overview
4+
5+
**Huanshankeji Gradle Common** is a collection of Gradle plugins and common dependencies for Kotlin projects. The repository provides convention plugins, dependency management, and build utilities primarily used by Huanshankeji for their Kotlin projects.
6+
7+
**High-level Repository Information:**
8+
- **Project Type:** Gradle plugin library with multiple modules
9+
- **Languages:** Kotlin (primary), Gradle Kotlin DSL
10+
- **Target Runtime:** JVM (JDK 17+, tested with JDK 17)
11+
- **Framework:** Gradle 9.0.0, Kotlin 2.2.20
12+
- **Size:** Medium-sized multi-module project (~20 plugin modules)
13+
- **APIs:** Experimental and subject to change
14+
15+
## Build Instructions
16+
17+
### Prerequisites
18+
- JDK 17 or higher (JDK 17 is used in CI)
19+
- Gradle wrapper handles Gradle version automatically
20+
21+
### Essential Build Commands
22+
23+
**Always run commands in the repository root directory.**
24+
25+
#### Bootstrap and Dependencies
26+
```bash
27+
# No special bootstrap needed - Gradle wrapper handles dependencies
28+
./gradlew --version # Verify Gradle 9.0.0 is used
29+
```
30+
31+
#### Build
32+
```bash
33+
./gradlew build # Full build (takes ~30 seconds, includes tests)
34+
./gradlew check # Run checks without building distributions (~1 minute)
35+
```
36+
37+
#### Test
38+
```bash
39+
./gradlew test # Run all tests (minimal test suite)
40+
```
41+
42+
#### Clean and Rebuild
43+
```bash
44+
./gradlew clean # Clean all build outputs
45+
./gradlew build # Rebuild from scratch
46+
```
47+
48+
#### Local Publishing
49+
```bash
50+
./gradlew publishToMavenLocal # Publish to local Maven repo (~2 seconds)
51+
```
52+
53+
#### Documentation Generation
54+
```bash
55+
./gradlew dokkaGeneratePublicationHtml # Generate API docs with Dokka
56+
./gradlew dokkaGenerate # Alternative Dokka generation command
57+
```
58+
59+
#### API Validation
60+
```bash
61+
./gradlew apiCheck # Check API compatibility against golden files
62+
./gradlew apiDump # Update API golden files for modules
63+
./gradlew validatePlugins # Validate plugin parameter annotations
64+
```
65+
66+
### Known Build Issues and Workarounds
67+
68+
**Warning Messages (Safe to Ignore):**
69+
- "Unsupported Kotlin plugin version" warnings related to Gradle Kotlin DSL compatibility
70+
- Deprecation warnings about `buildDir` usage
71+
72+
**Memory Requirements:**
73+
- JVM args set to `-Xmx2G` in `gradle.properties` for building architecture-common-gradle-plugins
74+
75+
**Bootstrap Dependencies:**
76+
- If the build fails with "Could not find com.huanshankeji:common-gradle-dependencies" error, run `./gradlew :common-gradle-dependencies:publishToMavenLocal` first
77+
- This typically happens after merging changes that update dependency versions
78+
79+
**Note:** The README mentions "./gradlew build needs to run twice to work" but this was not observed during testing.
80+
81+
## Project Layout and Architecture
82+
83+
### Module Structure
84+
```
85+
gradle-common/
86+
├── kotlin-common-gradle-plugins/ # Core Kotlin plugin conventions
87+
├── architecture-common-gradle-plugins/ # Web/architecture-specific plugins
88+
├── common-gradle-dependencies/ # Shared dependency versions
89+
├── huanshankeji-team-gradle-plugins/ # Team-specific utilities
90+
├── buildSrc/ # Build configuration and scripts
91+
├── .github/workflows/ # CI/CD pipelines
92+
└── gradle/wrapper/ # Gradle wrapper
93+
```
94+
95+
### Key Configuration Files
96+
97+
**Root Level:**
98+
- `build.gradle.kts` - Root build configuration with Dokka and plugin publishing
99+
- `settings.gradle.kts` - Module inclusion and dependency resolution
100+
- `gradle.properties` - Build properties (JVM args, Dokka settings)
101+
102+
**Build Configuration:**
103+
- `buildSrc/src/main/kotlin/VersionsAndDependencies.kt` - Centralized version management
104+
- `buildSrc/src/main/kotlin/Constants.kt` - Project constants
105+
- `buildSrc/build.gradle.kts` - Build dependencies and Kotlin version
106+
107+
**CI/CD:**
108+
- `.github/workflows/kotlin-jvm-ci.yml` - Main CI pipeline (Ubuntu, JDK 17)
109+
- `.github/workflows/dokka-gh-pages.yml` - Documentation deployment
110+
- `.github/workflows/copilot-setup-steps.yml` - Setup automation
111+
112+
### Major Components
113+
114+
**kotlin-common-gradle-plugins:** Convention plugins for Kotlin projects including:
115+
- `kotlin-jvm-library-*` plugins for JVM libraries
116+
- `kotlin-multiplatform-*` plugins for multiplatform projects
117+
- Maven publishing conventions
118+
- Sonatype OSSRH publishing
119+
120+
**architecture-common-gradle-plugins:** Web and architecture plugins including:
121+
- `GenerateKotlinJsBrowserWebrootForVertxWebPlugin` for Vert.x integration
122+
- Web frontend conventions
123+
- JavaScript browser distribution handling
124+
125+
**common-gradle-dependencies:** Centralized dependency versions in `CommonVersions.kt`
126+
127+
### Validation Pipeline
128+
129+
The repository uses GitHub Actions CI that:
130+
1. Runs on JDK 17 with Temurin distribution
131+
2. Executes `gradle-test-and-check` action
132+
3. Performs dependency submission for security scanning
133+
4. Generates API documentation with Dokka
134+
135+
**To replicate CI locally:**
136+
```bash
137+
./gradlew check # Equivalent to CI test-and-check
138+
./gradlew publishToMavenLocal # Verify publishing works
139+
./gradlew apiCheck # Verify API compatibility
140+
```
141+
142+
### Dependencies and Compatibility
143+
144+
**External Dependencies:**
145+
- Kotlin Gradle Plugin 2.2.20
146+
- Compose Multiplatform 1.10.0-alpha01
147+
- Dokka 2.1.0-Beta
148+
- Gradle Plugin Publish Plugin 2.0.0
149+
- Kotlin Binary Compatibility Validator 0.18.1
150+
151+
**Version Compatibility Notes:**
152+
- Gradle 9.0.0 required (handled by wrapper)
153+
- "Unsupported Kotlin plugin version" warnings are normal when the Kotlin Gradle plugin version is newer than the version bundled in Gradle
154+
- Compose Multiplatform versions constrain Kotlin version compatibility
155+
156+
### Development Guidelines
157+
158+
**IDE Setup (IntelliJ IDEA):**
159+
- Set Project SDK to JDK 17 or higher
160+
- Set Gradle JVM to "Project SDK"
161+
- Note: IntelliJ IDEA 2024.3 has loading issues (reported as IDEA-363846)
162+
163+
**Plugin Development:**
164+
- Script plugins in project sources may require IntelliJ restart for proper resolution
165+
- Use `publishToMavenLocal` to test changes in consuming projects
166+
167+
**Version Management:**
168+
- Plugin versions aligned via `alignedPluginVersion` in VersionsAndDependencies.kt
169+
- Common dependency versions in `commonGradleDependenciesVersion`
170+
- Snapshot versions used for development
171+
172+
### Key Source Files to Examine
173+
174+
**For Plugin Development:**
175+
- `kotlin-common-gradle-plugins/src/main/kotlin/com/huanshankeji/` - Core plugin implementations
176+
- `architecture-common-gradle-plugins/src/main/kotlin/com/huanshankeji/` - Architecture plugins
177+
178+
**For Version Management:**
179+
- `common-gradle-dependencies/src/main/kotlin/com/huanshankeji/CommonVersions.kt`
180+
- `buildSrc/src/main/kotlin/VersionsAndDependencies.kt`
181+
182+
**For Build Configuration:**
183+
- Files ending in `-conventions.gradle.kts` contain reusable build logic
184+
- `MavenPublishConventionsPlugin.kt` for publishing logic
185+
186+
## Trust These Instructions
187+
188+
This documentation is comprehensive and based on thorough exploration of the repository. Only perform additional searching if:
189+
- Specific implementation details are needed beyond what's documented
190+
- Instructions are found to be incorrect or incomplete
191+
- New features or changes are being implemented that require understanding code not covered here
192+
193+
The build commands and project structure documented here are validated and current as of the repository state.

0 commit comments

Comments
 (0)