Agent guide for maven-install-plugin

This file is read by automated agents (security scanners, code analyzers, AI assistants) operating on this repository.

Security

Security model: SECURITY.md

Agents that scan this repository should consult SECURITY.md and the threat model it links before reporting issues.

Compatibility

This branch is the 3.x line: it requires Maven 3.9.0 or later and Java 8. Code against the Maven 3.9 and Resolver 1.9 APIs only; Maven 4 APIs and code from the 4.x branch do not belong here.

  • Goal names, parameter names and user properties are public API. Never rename or remove one: maven.install.skip, installAtEnd, allowIncompleteProjects, and the install-file properties (file, pomFile, groupId, artifactId, version, packaging, classifier, sources, javadoc, generatePom, localRepositoryPath, extension).
  • Site pages under src/site are deep-linked from outside: do not rename a page or change a heading's anchor.
  • Fixes land here first and are forward-ported to maven-install-plugin-4.x. Known differences between the lines: installAtEnd defaults to false on 3.x and true on 4.x, and the install-file extension parameter exists only on 3.x.

Coding

Use test-first programming. Before fixing a bug or implementing a feature, write a test that exposes the bug and verify the test fails.

The bytecode floor is Java 8. Before submitting a PR, run mvn spotless:apply to format the files, then mvn verify. Run Spotless with JDK 17 or 21.

Tests

Unit tests are JUnit 5 (Jupiter) and live in src/test/java. New test code must not add JUnit 4, the vintage engine, Hamcrest, or org.codehaus.plexus.util; use JDK/Groovy APIs instead. Name tests after the behaviour they check, not after JIRA keys.

Integration tests in src/it are reserved for behaviour that needs a real Maven build: reactor and deferred installation, -T2 parallel builds, -f alternate POMs, embedded-POM execution and the setup-* support projects. Everything a mojo unit test can assert with a mocked session/repository belongs in src/test. Keep verify.groovy scripts in plain assert form.

The Maven 4 branch (maven-install-plugin-4.x) uses the Maven 4 @MojoTest harness. Its ArtifactInstaller is mocked, so maven-metadata-local.xml is not written during unit tests; assert the coordinate-derived paths from the install request instead of a physical file. The 3.x line's harness writes real files. Both branches keep the same IT names and test-case names, but do not share API-specific test code: 4.x stays Maven 4 only.

Run mvn -Prun-its verify for the full build, or mvn -o -B test spotless:check for the unit suite and formatting.