Fix javadoc generation blocking snapshot deployment

[Copilot]

Description

The maven-publish-snapshot workflow fails when running mvn javadoc:javadoc because Maven attempts to generate javadoc for sample modules whose artifacts are never installed to the local repository, causing dependency resolution failures.

Resolves #330

Changes

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

• Restrict javadoc generation to deployed modules only: xapi-model, xapi-client, xapi-model-spring-boot-starter
• Prevents Maven from processing sample modules that reference uninstalled artifacts
• Fixed typo in comment ("vaild" → "valid")

samples/pom.xml

• Add <skip>true</skip> to maven-javadoc-plugin configuration
• Ensures samples are excluded from javadoc generation at plugin level

Why the -pl switch is necessary

While the <skip>true</skip> configuration prevents javadoc generation for samples, Maven still processes all reactor modules and attempts to resolve their dependencies before executing plugins. Since sample modules depend on each other (e.g., get-statement → core) and have their install phase skipped, their artifacts aren't available in the local repository, causing dependency resolution failures. The -pl switch prevents Maven from processing sample modules entirely.

Checklist:

• Public methods are documented
• Public methods are tested
• New and existing tests pass when run locally
• There are no new warnings or errors

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Chore]: Fix deploy goal documentation publishing failures</issue_title>
<issue_description>### What

The Maven deploy goal (mvn deploy --file pom.xml) fails due to issues with documentation generation, specifically problems encountered when generating or publishing Javadoc or related docs. This prevents successful deployment of artifacts. Problems may stem from plugin misconfiguration, profile inclusion, or unintended publishing attempts from sample modules.

Why

This chore is necessary to ensure that documentation build errors do not block deployment. Addressing this will allow successful publication of project artifacts and avoid failed CI/CD deploys due to documentation issues.

Notes

• Documentation (e.g., Javadoc) fails during the deploy step, blocking artifact publication.
• Common causes include plugin misconfiguration or samples/test modules being published.
• Review the Maven plugin setup to ensure only intended modules generate or publish documentation during deploy.
• The repository configuration should explicitly skip documentation publish steps for sample/non-core modules.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Chore]: Fix deploy goal documentation publishing failures #330

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• repository.sonatype.org
  • Triggering command: /usr/lib/jvm/temurin-17-jdk-amd64/bin/java -classpath /home/REDACTED/work/xapi-java/xapi-java/.mvn/wrapper/maven-wrapper.jar -Dmaven.multiModuleProjectDirectory=/home/REDACTED/work/xapi-java/xapi-java org.apache.maven.wrapper.MavenWrapperMain -B javadoc:javadoc --file pom.xml (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[thomasturrell]

@copilot i suspect you will need to make similar changes for the non snapshot release which is in one of the other workflows.

[Copilot]

@copilot i suspect you will need to make similar changes for the non snapshot release which is in one of the other workflows.

Added a javadoc validation step to maven-publish.yml with the same -pl flag to ensure consistency and catch any javadoc issues before the release is published. Commit: cb777d8

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• repository.sonatype.org
  • Triggering command: /usr/lib/jvm/temurin-17-jdk-amd64/bin/java -classpath /home/REDACTED/work/xapi-java/xapi-java/.mvn/wrapper/maven-wrapper.jar -Dmaven.multiModuleProjectDirectory=/home/REDACTED/work/xapi-java/xapi-java org.apache.maven.wrapper.MavenWrapperMain -B release:prepare -DdryRun=true -Prelease -DskipTests -Dgpg.skip=true (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[thomasturrell]

@copilot please update the pr title and description to match the changes in the code.

[Copilot]

@copilot please update the pr title and description to match the changes in the code.

Updated understanding: The PR actually only fixes the maven-publish-snapshot workflow since the javadoc validation step added to maven-publish.yml was removed in commits 0edd9e7 and af7f86d.

Suggested PR title: "Fix javadoc generation blocking snapshot deployment"

Suggested PR description updates:

• Change "Both maven-publish-snapshot and maven-publish workflows fail" to "The maven-publish-snapshot workflow fails"
• Remove the section about maven-publish.yml changes
• Keep the sections about maven-publish-snapshot.yml and samples/pom.xml

The actual changes in this PR are:

1. .github/workflows/maven-publish-snapshot.yml - Added -pl xapi-model,xapi-client,xapi-model-spring-boot-starter flag and fixed typo
2. samples/pom.xml - Added <skip>true</skip> to maven-javadoc-plugin configuration

Note: I cannot directly update the PR title and description through the tools available to me, so you'll need to update them manually or let me know if you'd like me to make any code changes.