[#12288] Doc: <activation> limit on resolver-config profiles#1602
Open
ascheman wants to merge 2 commits into
Open
[#12288] Doc: <activation> limit on resolver-config profiles#1602ascheman wants to merge 2 commits into
ascheman wants to merge 2 commits into
Conversation
The aether.* properties declared in a settings.xml <profile> only take effect if the profile is listed under <activeProfiles> or activated via CLI -P. The limitation has been documented since MNG-7850 (2023), but only in the resolver-transport mini-guide -- users coming from the profile side never find it. * mini/guide-resolver-transport.md -- strengthen the NOTICE to enumerate all <activation> conditions affected (not just activeByDefault) and spell out the timing reason in one sentence. * introduction/introduction-to-profiles.md -- add a Note for resolver configuration sentence in the Active by default section, with cross-link to the mini-guide caveat. Wording is accurate for current Maven 3.x and Maven 4 RCs. apache/maven#12297 fixes the activeByDefault case on Maven 4 master; once that release ships and the backport question is settled, this doc should be updated to qualify the limitation to specific version ranges.
ascheman
added
bug
There was a problem hiding this comment.
Pull request overview
Note
Copilot couldn't run its full agentic review because no GitHub Actions runner was available. Make sure your repository has a runner available to run Copilot's review, or add a copilot-setup-steps.yml file specifying one with the runs-on attribute. See the docs for more details.
Clarifies documentation around the limitation that aether.* resolver configuration in settings.xml profiles is only applied when the profile is explicitly activated (via <activeProfiles> or CLI -P), not via <activation> conditions.
Changes:
- Expands the resolver transport mini-guide notice to explicitly list all
<activation>channels that are not honored for resolver session config. - Adds an explicit cross-guide note in the profiles introduction to warn users near the
<activeByDefault>documentation.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| content/markdown/guides/mini/guide-resolver-transport.md | Strengthens the NOTICE explaining which settings.xml profile activation modes affect resolver session configuration and why. |
| content/markdown/guides/introduction/introduction-to-profiles.md | Adds a note in the “Active by default” section pointing readers to the resolver-transport caveat and the required activation mechanism. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - only profiles activated by `settings/activeProfiles` will be taken for consideration - you can not use `profile/activation` in such case | ||
| **NOTICE:** Only profiles activated by `settings/activeProfiles` (the explicit list at the bottom of `settings.xml`) are honored here, or by CLI `-P <id>`. Profiles activated through `<activation>` conditions in the profile itself (`<activeByDefault>`, `<jdk>`, `<os>`, `<property>`, `<file>`) are **not** taken into account for the resolver session config -- the resolver session is built before Maven evaluates those conditions. | ||
|
|
||
| You can also use environment variable `MAVEN_OPTS` ot `MAVEN_ARGS` |
|
|
||
| **NOTICE** | ||
| - only profiles activated by `settings/activeProfiles` will be taken for consideration - you can not use `profile/activation` in such case | ||
| **NOTICE:** Only profiles activated by `settings/activeProfiles` (the explicit list at the bottom of `settings.xml`) are honored here, or by CLI `-P <id>`. Profiles activated through `<activation>` conditions in the profile itself (`<activeByDefault>`, `<jdk>`, `<os>`, `<property>`, `<file>`) are **not** taken into account for the resolver session config -- the resolver session is built before Maven evaluates those conditions. |
Contributor
Author
There was a problem hiding this comment.
Addressed in b01f578 — split the NOTICE into a two-bullet list of the honored activation channels (<activeProfiles> / CLI -P) and a separate sentence on why <activation> conditions aren't honored. Thanks for the suggestion.
* Fix typo on line 153: 'ot' -> 'or'. * Split the long single-sentence NOTICE into a two-bullet list of the honored activation channels plus a separate sentence on rationale, per Copilot suggestion at line 151.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR does
Two doc clarifications around the long-standing limitation that
aether.*properties declared inside asettings.xmlprofile only take effect if the profile is listed under<activeProfiles>or activated via CLI-P. The limitation has been documented since MNG-7850 (2023, by @slawekjaranowski) but only in the resolver-transport mini-guide; profile-side users would never find it.guides/mini/guide-resolver-transport.md— strengthen the NOTICE so it enumerates what the limitation actually covers (all<activation>conditions, not justactiveByDefault) and gives a one-line rationale.guides/introduction/introduction-to-profiles.md— add a single sentence in the "Active by default" section linking to the mini-guide caveat, so users planning to use<activeByDefault>foraether.*config are warned where they actually look.Versions affected
The doc page describes a limitation that exists in every Maven release on the user's path; it remains accurate for years of running releases. The "remaining four channels" caveat (
<jdk>,<os>, etc.) is true regardless of whether a WARN is added later.