Contributing Spring Boot 3.0.0 Upgrade recipes

[fabapp2]

We are working on a recipe for automated upgrades to Spring Boot 3.0.0.

We appreciate all contributions and to ease the process and entry barrier here's some information to help new contributors getting started.

The issues that (hopefully) contain enough information to get started are tagged with good first issue.

How to get started

• Look at issues labeled good first issue
• Pick one that interests you and makes sense to you.
• Add a comment letting us know that you'd like to work on the issue
• We'll add a comment assigned-to: @your-handle
• You're working in the issue
• Create a fork (pressing the fork button on top)
• Commit to your fork
• Push and create a PR (there'll be a button in the web-ui)
• If you haven't already you'll be asked to sign the contributor agreement
• See the Definition of Done (below)
• If you're having questions you want to discuss or want to get feedback early on, create a draft-PR to let us know it's not ready (yet)
• We'll review the PR and maybe ask for changes
• As soon as the review is complete and the PR builds (see actions and Concourse Pipeline) we'll merge the changes and you're a contributor 🚀

Few recommendations

• Please try not to format other code than the code you touched to avoid too many (unrelated) changes
• Please try to work only on issue-related sources (I know it's hard sometimes) so we can link one PR to one issue if possible
• Don't hesitate to ask any questions you have. We're there to help and we're glad you're willing to contribute ❤️

If you have not previously done so, please sign the Contributor License Agreement. You will be reminded automatically when you submit the pull request.

All contributions are welcome.

Please refer to the CONTRIBUTING.adoc for more details.

Spring Boot 3 Upgrade

Issues to create reports are tagged as upgrade-boot:report and the ones with a migration are tagged as upgrade-boot:migration.

Two recipes exist related to Upgrades form Sprig Boot 2.7.x to Spring Boot 3.0.x.

. boot-2.7-3.0-upgrade-report.yaml - Creating a report that informs users about applicable changes that can't be automated. Perfect would be a report that also covers the changes for which an automated recipe exists. This would show the required changes for a given application, but that's not how we started. So until now only non-automatable changes are reported in the report.
2. boot-2.7-3.0-dependency-version-update.yaml - Running automated migrations and actually change resources and code

Report

The report is created from the boot-2.7-3.0-upgrade-report.yaml recipe.

The report recipe is meant to be applied before the migration.
It creates a HTML file from Asciidoc filtering the changes relevant to the scanned application.

We think the report itself provides already value to customers as it

• Filters irrelevant sections from the Release Notes
• Provides additional information and guidance
• Does not change / break anything

Creating a report takes two components, a Finder and a SectionBuilder

For an example of how to create a new section in the report see

• DatabaseDriverGaeFinder
• DatabaseDriverGaeSectionBuilder
• DatabaseDriverGaeSectionBuilderTest

The SectionBuilder must be annotated as @Component and the result of the isApplicable() method defines if the SectionBuilder will be used to generate a report. There's nothing more that needs to be configured to add a section to the report.

Creating a report section first (maybe only) has some upsides and comes as kind of precondition to provide an automated migration:

• A Finder analyses the scanned application and provides access to resources and code that makes a change relevant for a given application. This is a natural first step when thinking about migration.
• The information provided to the user of what needs to be done might reflect an algorithm for an (later) automated migration

Migration

Automated migrations must be declared in the boot-2.7-3.0-dependency-version-update.yaml recipe.

When possible try to declare migrations as OpenRewrite recipes so we can easily contribute these to OpenRewrite later on. See the documentation for How to integrate OpenRewrite recipes in SBM and the OpenRewrite documentation.

Documentation & Resources

Find the current developer-documentation here

Relevant resources:

• Concepts
• Declarative Recipes
• Maven multi-module support
• Using OpenRewrite recipes
• TestProjectContext

Definition of Done

To get a PR merged...

• The code should to be tested.
• Tests should exist for single-module setup and for multi-module projects
• Reusable components (e.g. a Finder) should have their own test.
• New Actions doing migration need to be declared in boot-2.7-3.0-dependency-version-update.yaml.
• Test/assertion for such actions should also be added to BootUpgrade_27_30_IntegrationTest, BootUpgrade_27_30_ManuallyManaged_IntegrationTest and BootUpgrade_27_30_ManuallyManaged_IntegrationTest