docs: clarify deprecation of RELEASE and LATEST version constants

[amahi1568]

What was done

Added JavaDoc guidance for deprecated artifact version constants to clarify recommended alternatives.

Why

The deprecated RELEASE and LATEST version tokens provided no migration guidance, which could confuse users.

Scope

Documentation-only change. No functional impact.

[cstamas]

The LATEST and RELEASE meta versions have been deprecated since Maven 3.0, this change is incorrect.

[amahi1568]

Thanks for the clarification. I misunderstood the deprecation timeline for LATEST and RELEASE. I’ll close this PR accordingly.

…

On Fri, Jan 30, 2026 at 1:32 AM Tamas Cservenak ***@***.***> wrote: *cstamas* left a comment (apache/maven#11686) <#11686 (comment)> The LATEST and RELEASE meta versions have been deprecated since Maven 3.0, this change is incorrect. — Reply to this email directly, view it on GitHub <#11686 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BV47V2RK2T7C3COCPRGCAG34JJRN7AVCNFSM6AAAAACTLJ7KHKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTQMRQGAYDSMZQGI> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[desruisseaux]

Instead of closing the PR, maybe just replace it by the addition of the since = "3.0" attribute in @Deprecated. It would avoid the same confusion to happen again.

[amahi1568]

Thanks for the suggestion. I’ve updated the PR to add the correct
@deprecated(since = "3.0") attribute for RELEASE and LATEST constants,
so the deprecation timeline is clear and avoids future confusion.

[elharo]

No need to duplicate the since parameter

[elharo]

never use version ranges

[gnodet]

Claude Code on behalf of Guillaume Nodet

Thanks for improving the documentation. A few issues to address:

1. since version change is incorrect: The @Deprecated annotation currently says since = "4.0.0" on master. Changing it to "3.0" is not accurate — the @Deprecated annotation itself was added in 4.0.0. While RELEASE/LATEST resolution may have been discouraged earlier, the formal deprecation marker was introduced in 4.x. Please revert this change and keep since = "4.0.0".

2. As @elharo already noted, the Javadoc @deprecated tag duplicates what the @Deprecated(since=...) annotation already conveys. If you want to add guidance, a plain Javadoc comment without @deprecated would be sufficient, since the annotation already handles the deprecation signal.

3. Also as @elharo noted, recommending "version range" as an alternative to LATEST is not good advice.

Please address the existing review feedback before this can move forward.

[gnodet]

The since value should remain "4.0.0" — that is when the @Deprecated annotation was actually added to these constants. Changing it to "3.0" without evidence from the git history is inaccurate.

Also, the Javadoc asterisks are misaligned — they should use * (space-star) to match the project's formatting conventions:

Suggested change

	@Deprecated(since = "3.0")
	* @deprecated since 3.0
	* Use explicit version resolution instead of special version constants.

should be (if kept at all):

Suggested change

	@Deprecated(since = "3.0")
	* @deprecated Since 4.0.0. Use explicit version resolution instead of special version constants.

[gnodet]

Changing @Deprecated(since = "4.0.0") to @Deprecated(since = "3.0") is incorrect. The deprecation annotation was introduced in Maven 4.0.0. Please revert.

Suggested change

	String RELEASE_VERSION = "RELEASE";
	@Deprecated(since = "4.0.0")