spring-projects / spring-projects/spring-framework

Revamp documentation to prioritize Annotation-Based configuration over XML

Open
#35,446 2 comments 4 reactions 1 assignee View on GitHub

@sdeleuze is already working on this.

Since Sep 9, 2025.

type: documentation
Dominant language
Java
Stars
60.2k
Forks
38.8k
Avg merge
5d 2h
Merged PRs (30d)
27

Description

The current reference documentation shows XML configuration as the primary configuration style in some sections. While XML is still supported, it has not been the mainstream choice for more than a decade. XML examples can make the framework feel outdated and newcomers may get the wrong impression that XML is still recommended.

It would be helpful to reframe the introduction of configuration approaches in the The IoC Container section to align the documentation with the current Spring usages and show Java/Annotation-Based configuration first.

Also, examples in sections like: Resources, Validation, Data Binding, and Type Conversion, Transaction Management, Initializing a DataSource, Object Relational Mapping (ORM) Data Access, Marshalling XML by Using Object-XML Mappers, Locale, View Technologies could show default examples in Java-config and keep the XML equivalent in a hidden secondary tab for reference.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.