[wagon-3.x] Add user, developer and HTTP configuration guides

[slachiewicz]

Three guides that have been requested for a long time.

Closes #191 (WAGON-1, open since 2004). Closes #190 (WAGON-3, open since 2004). Closes #490 (WAGON-425, open since 2014).

Page	Covers
user-guide.md	What a Wagon is; provider → role hint → URL scheme for all eight providers; obtaining one as a build extension or by lookup; the connect/get/put/disconnect lifecycle with working code; a capability matrix; Repository URL parsing including credentials being stripped from getUrl(); AuthenticationInfo; proxies and nonProxyHosts globbing; the two timeouts; streaming versus file transfer; listeners, including that transferProgress runs synchronously on the transfer thread; the exception table with the actual message wording
developer-guide.md	The SPI; what AbstractWagon provides and the two methods a provider must supply; StreamWagon's contract and when it does not fit; both registration mechanisms — the @plexus.component tag and a hand-written components.xml; wagon-provider-test and what you inherit from WagonTestCase; the HTTP TCK, its use-case ids, and how to wire it in and mark a case unsupported; running the suites
http-configuration.md	The <server><configuration> block for wagon-http; httpConfiguration and the six HttpMethodConfiguration properties; the merge semantics and their consequences; both XML spellings Plexus accepts; all 17 recognised params keys mapped to their RequestConfig setters; auth schemes, preemptive auth, scope overrides, proxy and NTLM; the deprecated httpHeaders; 429 backoff; the system-property reference

Everything is grounded in the source. Where something could not be verified from this repository it was left out rather than guessed — noted below.

mvn site builds. The rendered HTML was checked rather than just the exit code, which caught one real defect: Doxia generates heading ids as What_a_Wagon_is, not the kebab-case GitHub form, so the cross-page anchors were dead until corrected.

Deliberately not covered

How settings.xml populates ProxyInfo.ntlmHost/ntlmDomain (that mapping lives in Maven core), how Resolver's wagon transport picks a provider (out of this repository), and which of wagon-http or wagon-http-lightweight wins when both are on the class path (the container decides, not Wagon).

Things found in the code while writing this

Documented where they affect the reader, not fixed here, and worth separate issues:

• usePreemptive never survives a merge. HttpMethodConfiguration.copy() does not copy it and ConfigurationUtils.merge() never applies it, so whenever both <all> and the block for a method are present the effective value is always false. HttpWagonPreemptiveTest passes only because it sets <all> alone.
• NTLM against the target server cannot work. NTCredentials is only ever constructed for a proxy, so the registered NTLM scheme has nothing usable to offer an NTLM-protected repository. This is the most likely way a reader of WAGON-425 would be misled.
• PUT is always preemptively authenticated, regardless of configuration; the source carries // FIXME Perform only when preemptive has been configured.
• Per-method timeouts cannot be set back to the default value, because the merge only takes them when they differ from Wagon.DEFAULT_*.
• BasicAuthScope's javadoc documents /server/proxyBasicAuth, which matches no field; the field is proxyAuth.
• README.md tells contributors to run mvn -Prun-its verify. There is no run-its profile anywhere in this repository.
• wagon-tcks/wagon-tck-http/sample-tck-consumer is in no <modules>, still 1.0-SNAPSHOT against decade-old dependencies, and is the only thing resembling "how to consume the TCK". The guide documents the real wiring from wagon-http's TckTest instead.

The four provider pages carrying the "removed in version 4.0.0" notice were left alone. The new pages describe what exists and do not repeat that claim.

[slachiewicz]

Second commit added, and it turned up a code defect worth knowing about before review.

Writing the corrected BasicAuthScope javadoc meant actually reading the realm branch, and both arms of its if/else assign the same thing — so <realm>ANY</realm> sets the literal string ANY rather than AuthScope.ANY_REALM, while host and port next to it map ANY correctly. Filed as #910. The code is untouched here; fixing it is a behaviour change and belongs in its own PR.

That also means this PR's first commit had it wrong: http-configuration.md said each of host, port and realm accepts ANY to mean "match anything". The second commit corrects that to describe the asymmetry, keeps the all-ANY example with a note that it only works through the early short circuit, and adds an example showing that widening host and port means omitting realm.

Also in this commit: a developer-guide subsection on running the TCK classes rather than subclassing them from your own package. The use-case id is recovered by walking the stack for the last method before the first frame outside getClass().getPackage().getName(), so a consumer subclassing from elsewhere gets Cannot run test: null on every case, each treated as unsupported — a suite that goes green without testing anything.

Site still builds; the new heading and the corrected text were checked in the rendered HTML.

[Copilot]

Pull request overview

Adds long-requested Maven Wagon documentation guides to the project site, covering end-user usage, provider development/testing, and wagon-http configuration, plus a small Javadoc clarification to align source docs with the new HTTP guide content.

Changes:

• Add three new site pages: User Guide, Development & Testing Guide, and HTTP Configuration guide.
• Expose the new guides in the Maven Site navigation (src/site/site.xml).
• Clarify BasicAuthScope#getScope(...) Javadoc to describe its override semantics and the special handling of "ANY" and realm matching.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
wagon-providers/wagon-http-shared/src/main/java/org/apache/maven/wagon/shared/http/BasicAuthScope.java	Updates Javadoc to accurately describe AuthScope override/ANY behavior referenced by the new HTTP configuration guide.
src/site/site.xml	Adds a “Guides” menu linking the new pages into the generated site navigation.
src/site/markdown/user-guide.md	Introduces an end-user guide covering Wagon lifecycle, providers, auth, proxies, timeouts, streaming, listeners, and error mapping.
src/site/markdown/developer-guide.md	Introduces a provider-focused guide for SPI, registration mechanisms, provider-test usage, HTTP TCK wiring, and running tests/site.
src/site/markdown/http-configuration.md	Documents wagon-http <server><configuration> options and how they map to HttpClient 4.5 behavior, including merge semantics and params keys.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.