Skip to content

Add developer and AI documentation #385

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
keeganwitt merged 1 commit into from
Jun 22, 2026
Merged

Add developer and AI documentation #385

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Agent Instructions

## Toolchain
- Use the Maven Wrapper: `./mvnw` on Unix and `./mvnw.cmd` on Windows.
- Build with Maven 3.9.12+ and Java 11+; production bytecode and APIs must remain Java 8 compatible.

## Project Model
- This is a Maven plugin (`maven-plugin` packaging); Mojo metadata comes from `@Mojo` and `@Parameter` annotations and generates the plugin descriptor.
- Preserve each Mojo's goal, default lifecycle phase, dependency-resolution scope, and parameter compatibility unless the change explicitly alters plugin behavior.
- Do not edit generated files in `target/`.

## Groovy and Compatibility
- Do not add production compile-time dependencies on Groovy APIs; Groovy is supplied by the consuming project at runtime.
- Use `ClassWrangler`, the existing classloader boundaries, version checks, and reflection helpers to call version-dependent Groovy APIs.
- Preserve clear exception translation around reflective calls; never replace a compatibility fallback with a hard dependency on one Groovy version.
- Changes to reflection or compatibility code need focused tests and must pass the Groovy 2.5, 3, 4, and 5 CI matrix in `.github/workflows/ci.yaml`.
- Treat `src/main/java/org/codehaus/gmavenplus/groovyworkarounds` as a compatibility boundary: preserve version guards and their rationale; update focused unit tests and an Invoker test when compiler behavior changes.
- Treat `src/main/java/org/codehaus/gmavenplus/javaparser` as upstream-derived compatibility code: retain provenance and update related language-level constants and feature mappings together.

## Tests
- Put isolated Mojo behavior, parameters, version gates, reflection failures, and utility behavior in `src/test/java` unit tests.
- Add `src/it/<project>` Maven Invoker tests only for real consuming-build behavior: lifecycle wiring, classpaths, Groovy compilation, generated stubs, multi-module builds, or configuration interactions.
- Do not add integration-test combinations mechanically; cover distinct user-visible workflows and regressions that unit tests cannot establish.

## References
| Need | File |
|---|---|
| Build, plugin metadata, and Invoker configuration | `pom.xml` |
| CI compatibility matrix | `.github/workflows/ci.yaml` |
| Common local, release, and maintenance commands | `DEVELOPER_NOTES.md` |
| Project and user documentation | `README.md` |
60 changes: 60 additions & 0 deletions DEVELOPER_NOTES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# Developer Notes

Use `./mvnw` on Unix or `./mvnw.cmd` on Windows for routine development. The commands below use the Windows wrapper; replace it with `./mvnw` on Unix.

## Everyday Development
| Task | Command |
|---|---|
| Run unit tests | `./mvnw.cmd test` |
| Run one unit-test class | `./mvnw.cmd -Dtest=ClassNameTest test` |
| Run the full test suite | `./mvnw.cmd -Dmaven.javadoc.skip=true -Dmaven.source.skip=true -Dgpg.skip=true clean install invoker:install invoker:run` |
| Run integration tests only | `./mvnw.cmd -Dmaven.test.skip=true -Dmaven.javadoc.skip=true -Dmaven.source.skip=true -Dgpg.skip=true clean install invoker:install invoker:run` |
| Run selected integration projects | `./mvnw.cmd -Dmaven.test.skip=true -Dmaven.javadoc.skip=true -Dmaven.source.skip=true -Dgpg.skip=true -Dinvoker.test=basicCompile,advancedCompile clean install invoker:install invoker:run` |
| Install without tests or Invoker projects | `./mvnw.cmd -Dmaven.test.skip=true -Dinvoker.skip=true -Dmaven.javadoc.skip=true -Dmaven.source.skip=true -Dgpg.skip=true clean install` |

## Site and Dependency Maintenance
| Task | Command |
|---|---|
| Generate and stage the site | `./mvnw.cmd clean site site:stage` |
| Generate and stage the site without tests | `./mvnw.cmd -Dmaven.test.skip=true -DskipITs clean site site:stage` |
| Deploy the site | `./mvnw.cmd clean site-deploy` |
| Update the Maven Wrapper | `mvn wrapper:wrapper -Dmaven=[Desired Maven version]` |
| Show available dependency, property, and plugin updates | `./mvnw.cmd versions:display-dependency-updates versions:display-property-updates versions:display-plugin-updates` |
| Show runtime dependencies | `./mvnw.cmd dependency:tree -Dscope=runtime` |
| Show test dependencies | `./mvnw.cmd dependency:tree -Dscope=test` |
| Show compile dependencies | `./mvnw.cmd dependency:tree -Dscope=compile` |

## Release

1. Ensure `gpg-agent` is running.
2. Verify signing: `echo "test" | gpg --clearsign` on Linux/Cmd, or `Write-Host "test" | gpg --clearsign` in PowerShell.
3. Run `mvn clean release:prepare`, then `mvn release:perform`.
4. Verify the plugin with a test project and run `publish.sh` or `publish.ps1`.
5. Fetch from origin, create the next GitHub version, and update the [Usage](https://github.com/groovy/GMavenPlus/wiki/Usage) and [Examples](https://github.com/groovy/GMavenPlus/wiki/Examples) wiki pages.
6. Update the [Android example](https://github.com/keeganwitt/android-gmavenplus-example).
7. Announce the release on `gmavenplus@googlegroups.com` and `users@groovy.apache.org`.
8. Post on Twitter/X with `#GMavenPlus` and `#GroovyLang`.
9. Announce in the [Groovy Community Slack](https://groovy-community.slack.com/messages/C2SLAV9FY/).

### Release Dry Run
- Add `-DdryRun=true` to the release command.

### Redeploy After a Signing Failure

1. Start `gpg-agent` and verify signing as above.
2. Check out the `prepare release` commit and copy `pom.xml` to `target/gmavenplus-plugin-<version>.pom`.
3. Deploy each artifact with the copied POM and `https://ossrh-staging-api.central.sonatype.com/service/local/staging/deploy/maven2`:

```text
mvn gpg:sign-and-deploy-file -DpomFile=target/gmavenplus-plugin-<version>.pom -Dfile=target/gmavenplus-plugin-<version>.pom -Durl=https://ossrh-staging-api.central.sonatype.com/service/local/staging/deploy/maven2 -DrepositoryId=ossrh
mvn gpg:sign-and-deploy-file -DpomFile=target/gmavenplus-plugin-<version>.pom -Dfile=target/gmavenplus-plugin-<version>.jar -Durl=https://ossrh-staging-api.central.sonatype.com/service/local/staging/deploy/maven2 -DrepositoryId=ossrh
mvn gpg:sign-and-deploy-file -DpomFile=target/gmavenplus-plugin-<version>.pom -Dfile=target/gmavenplus-plugin-<version>-sources.jar -Dclassifier=sources -Durl=https://ossrh-staging-api.central.sonatype.com/service/local/staging/deploy/maven2 -DrepositoryId=ossrh
mvn gpg:sign-and-deploy-file -DpomFile=target/gmavenplus-plugin-<version>.pom -Dfile=target/gmavenplus-plugin-<version>-javadoc.jar -Dclassifier=javadoc -Durl=https://ossrh-staging-api.central.sonatype.com/service/local/staging/deploy/maven2 -DrepositoryId=ossrh
```

## Publishing
| Task | Command |
|---|---|
| Package and sign | `mvn -Dmaven.test.skip=true clean verify` |
| Deploy a tested snapshot | `mvn -Dmaven.test.skip=true -Dinvoker.skip=true clean deploy` |
| Deploy a new snapshot | `mvn clean deploy` |
Loading