Fix documentation issues across site docs

[elharo]

Fixes multiple issues across 14 site documentation files:

• creating-a-repository-system-session.md: Fix broken Java code (undefined variable, wrong class reference)
• deployment.md: Fix heading level, fix BasicRepositoryConnectorFactory/BasicRepositoryConnector link mismatch
• local-repository.md: Fix shell code examples (language tags, missing line continuation), doubled word
• api-compatibility.md: Fix contradictory version policy statements, grammar fixes
• about-checksums.md: Fix "so to say" -> "so to speak", "infer" -> "imply", "nothing prevent" -> "prevents"
• common-misconceptions.md: Grammar fixes
• how-resolver-works.md: Missing article, awkward phrasing, stray empty list item
• remote-repository-filtering.md: Stray period, "procided" -> "provided", missing preposition
• repository-key-function.md: Missing possessive apostrophe
• third-party-integrations.md: "into" -> "in"
• transporter-known-issues.md: Missing "in"
• upgrading-resolver.md: "sans" -> "except", "it's" -> "its", grammar fixes
• what-is-resolver.md: Trailing "is"
• index.xml: Missing alt attribute on image

[gnodet]

Two confirmed issues in documentation changes: (1) the code example in creating-a-repository-system-session.md passes a SessionBuilder to newLocalRepositoryManager(), which expects a RepositorySystemSession — this will not compile; (2) minor indentation inconsistency in api-compatibility.md.

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

Claude Code on behalf of gnodet

[gnodet]

The fix correctly replaces the undefined session variable and SessionBuilderSupplier, but system.newLocalRepositoryManager(sessionBuilder, localRepo) will not compile: newLocalRepositoryManager expects a RepositorySystemSession as its first argument, and SessionBuilder does not extend RepositorySystemSession.

The SessionBuilder API provides withLocalRepositories(LocalRepository...) for this purpose, which would make the example both simpler and correct:

Suggested change

	RepositorySystemSession.SessionBuilder sessionBuilder = system.createSessionBuilder();
	LocalRepository localRepo = new LocalRepository( "target/local-repo" );
	sessionBuilder.setLocalRepositoryManager( system.newLocalRepositoryManager( session, localRepo ) );
	sessionBuilder.setLocalRepositoryManager( system.newLocalRepositoryManager( sessionBuilder, localRepo ) );
	return session.build();
	return sessionBuilder.build();
	}
	```
	RepositorySystemSession.SessionBuilder sessionBuilder = system.createSessionBuilder();
	LocalRepository localRepo = new LocalRepository( "target/local-repo" );
	sessionBuilder.withLocalRepositories( localRepo );
	return sessionBuilder.build();

[Copilot]

Pull request overview

This PR updates the Maven Resolver site documentation to correct broken examples, improve clarity/grammar, and address an accessibility gap in the site index.

Changes:

• Fix and modernize documentation examples (notably session creation and shell snippets).
• Clarify version-compatibility wording and correct various grammar/typos across multiple pages.
• Improve site accessibility by adding missing image alternative text.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/site/xdoc/index.xml	Adds an alt attribute to the dependency diagram image for accessibility.
src/site/markdown/what-is-resolver.md	Removes a trailing stray “is” and fixes sentence punctuation.
src/site/markdown/upgrading-resolver.md	Improves wording/grammar (“its”, “except”, sentence clarity).
src/site/markdown/transporter-known-issues.md	Fixes missing preposition in explanatory text.
src/site/markdown/third-party-integrations.md	Fixes phrasing (“in our way”).
src/site/markdown/repository-key-function.md	Fixes missing possessive apostrophe.
src/site/markdown/remote-repository-filtering.md	Fixes punctuation/typos and improves explanatory sentence clarity.
src/site/markdown/local-repository.md	Corrects code block language tags/line continuations and fixes wording.
src/site/markdown/how-resolver-works.md	Fixes phrasing and removes a stray empty list item.
src/site/markdown/deployment.md	Fixes heading level and corrects connector reference text/link mismatch.
src/site/markdown/creating-a-repository-system-session.md	Updates the Java example for creating a RepositorySystemSession.
src/site/markdown/common-misconceptions.md	Improves wording and fixes minor grammar issues.
src/site/markdown/api-compatibility.md	Updates version policy wording and improves historical explanation text.
src/site/markdown/about-checksums.md	Improves wording/grammar and corrects phrasing around checksums.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[gnodet]

Thanks for fixing the indentation issue in api-compatibility.md and the grammar fix in common-misconceptions.md!

The compile issue in creating-a-repository-system-session.md still remains — system.newLocalRepositoryManager(sessionBuilder, localRepo) won't compile because SessionBuilder doesn't extend RepositorySystemSession.

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

Claude Code on behalf of gnodet

[gnodet]

This still won't compile: all three overloads of newLocalRepositoryManager require a RepositorySystemSession as the first argument, and SessionBuilder does not extend RepositorySystemSession.

The SessionBuilder API provides withLocalRepositories(LocalRepository...) for exactly this purpose:

Suggested change

	RepositorySystemSession.SessionBuilder sessionBuilder = system.createSessionBuilder();
	LocalRepository localRepo = new LocalRepository( "target/local-repo" );
	sessionBuilder.setLocalRepositoryManager( system.newLocalRepositoryManager( session, localRepo ) );
	sessionBuilder.setLocalRepositoryManager( system.newLocalRepositoryManager( sessionBuilder, localRepo ) );
	return session.build();
	return sessionBuilder.build();
	RepositorySystemSession.SessionBuilder sessionBuilder = system.createSessionBuilder();
	LocalRepository localRepo = new LocalRepository( "target/local-repo" );
	sessionBuilder.withLocalRepositories( localRepo );
	return sessionBuilder.build();

[gnodet]

Thanks for addressing the compile error! However, the fix switched to new DefaultRepositorySystemSession(), whose no-arg constructor is @Deprecated with a javadoc warning that it "leads to resource leaks" and should be replaced with RepositorySystem.createSessionBuilder(). A documentation example should demonstrate the recommended API.

Also, the surrounding prose still references maven-resolver-supplier classes and RepositorySystemSession.SessionBuilder, which the code no longer uses — creating an inconsistency between the text and the example.

The suggestion from the previous review would resolve both issues:

RepositorySystemSession.SessionBuilder sessionBuilder = system.createSessionBuilder();

LocalRepository localRepo = new LocalRepository( "target/local-repo" );
sessionBuilder.withLocalRepositories( localRepo );

return sessionBuilder.build();

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

Claude Code on behalf of gnodet

[gnodet]

New issues introduced in about-checksums.md — unmatched parentheses and a missing word. The previously raised concern about the deprecated DefaultRepositorySystemSession() constructor in creating-a-repository-system-session.md also remains.

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

Claude Code on behalf of gnodet