v5.1.0 GA release plan

[stokpop]

Background

Per RFC-0050 (Java Buildpack Migration to Golang):

v5.0.x - Experimental release intended to get broad feedback by users, incompatible changes may happen
v5.1.0 - First non-experimental GA release

This issue tracks the doc/messaging work needed to formally mark v5.1.0 as GA, plus a deferred docs.cloudfoundry.org refresh section for later follow-up.

Version bump

To go to next minor VERSION a file edit is needed for this GA transition, from 5.0.x to 5.1.0.

Note: patch version bumping is owned by the external Concourse java-buildpack/cf-release pipelines (see cloudfoundry/buildpacks-ci release guide, docs/cf-release-buildpack-guide.md).

Changes since v5.0.0 — verified, with a caveat

Scanned git log v5.0.0..HEAD (336 commits): no new intentionally-breaking API/config changes were introduced (no removed frameworks, no default-value flips beyond what v5.0.0 already announced).

However, there are many bug-fix commits since v5.0.0 that changed previously-buggy/inconsistent runtime behavior. These are fixes "for the better" (bring behavior in line with intent), but are still observable behavior changes some upgrading apps could notice. Notable examples:

• Fix JBP_CONFIG_JAVA_MAIN not taking effect when app is detected as Spring Boot — silently-ignored config now applies
• Fix SERVER_PORT/$PORT injection for Spring Boot JAR, Spring Boot CLI, and generic profile.d scripts (previously not shell-expanded correctly)
• Fix LoadConfig reading the wrong JBP_CONFIG_*_JRE vendor prefix — configs could previously silently apply to the wrong JRE vendor
• Restrict -XX:ActiveProcessorCount to HotSpot JREs only (previously applied incorrectly to non-HotSpot JREs like IBM/OpenJ9)
• Tomcat allowSchemeMismatch=true change for server.xml
• Multiple Tomcat context_path/ROOT.xml/WAR-filename XML-escaping fixes — changes generated Tomcat context descriptors for non-root context paths
• Multiple JAVA_OPTS/USER_JAVA_OPTS assembly-script quoting/escaping fixes (multiline values, $DEPS_DIR/$HOME substitution, bash 5.1 compatibility)
• Java-version-detection fallback-to-default behavior fixes/clarifications

Recommendation: don't label these as breaking changes, but do call them out in a "Notable fixes since v5.0.0" section in the v5.1.0 GA release notes so upgrading users aren't blindsided.

In-repo todos (java-buildpack)

• Fix broken link in README.md: ruby_vs_go_buildpack_comparison.md → RUBY_VS_GO_BUILDPACK_COMPARISON.md (case mismatch breaks on case-sensitive filesystems/GitHub)
• Add explicit GA-status note in README.md (near "Ruby vs Go Migration Status"), referencing RFC-0050, stating v5.1.0 is the first non-experimental GA release
• Update ARCHITECTURE.md migration-status header to reference the v5.1.0 GA milestone
• Update RUBY_VS_GO_BUILDPACK_COMPARISON.md "Migration Status" line to explicitly reference GA / v5.1.0
• Review adoption-migration-details.md for any lingering pre-GA/future-tense wording
• Add a short GA release-notes doc/section for v5.1.0 (modeled on the v5.0.0 GitHub release notes, minus the "Experimental Release" banner), including the "Notable fixes since v5.0.0" list above
• Validate internal doc cross-links after edits

Out of scope: docs.cloudfoundry.org updates

As a reminder, docs.cloudfoundry.org (cloudfoundry/docs-buildpacks) also needs a refresh -- not part of this issue's PRs.

Found while researching GA readiness; documented here for later follow-up (separate repo/issue/PR, not tackled now):

1. java/java-tips.html.md.erb references config/open_jdk_jre.yml — Go buildpack has no config/*.yml, uses manifest.yml only
2. Example CLI transcripts across multiple pages show JDK 1.8.0_25/1.8.0_342 and .java-buildpack/open_jdk_jre paths — v5 defaults to Java 17 and uses a different JRE path (hardcoded .java-buildpack/... paths break per the v5.0.0 release notes; must use $JAVA_HOME)
3. getting-started-deploying-apps/gsg-grails.html.md.erb, gsg-ratpack.html.md.erb, gsg-spring.html.md.erb reference JDK 1.6/1.7/1.8 support — outdated for v5
4. gsg-ratpack.html.md.erb — Ratpack is no longer separately detected in the Go buildpack (folded into Dist Zip, "version detection lost" per our own migration comparison doc); this dedicated getting-started guide needs rework/deprecation notice
5. configuring-service-connections.html.md.erb — describes Spring Auto Reconfiguration as installed by default with a 2022-era Ruby-buildpack deprecation timeline; v5 (Go) disables it by default — page needs updating
6. None of the fetched pages currently mention the Go rewrite, RFC-0050, or the v5.1.0 GA milestone
7. Outdated Maven/Gradle dependency version examples:
   • configuring-service-connections.html.md.erb pins io.pivotal.cfenv:java-cfenv(-jdbc/-boot):2.4.0 — current buildpack-shipped version (manifest.yml) is 4.0.2 (also 3.5.3), two major versions behind
   • java-client.html.md.erb Maven snippet pins org.cloudfoundry:cloudfoundry-client-reactor:2.0.0.BUILD-SNAPSHOT, cloudfoundry-operations:2.0.0.BUILD-SNAPSHOT, io.projectreactor:reactor-core/reactor-netty:2.5.0.BUILD-SNAPSHOT — ancient pre-release/SNAPSHOT coordinates for cf-java-client (not buildpack-owned, but stale/misleading on the same java/ docs tree)
8. Incorrect "Spring Cloud Profile" migration claim — configuring-service-connections.html.md.erb (#migrating-cloud-profile) says the cloud Spring profile requires Spring Auto Reconfiguration and instructs manually setting SPRING_PROFILES_ACTIVE=cloud if you don't use it. Inaccurate for the Go buildpack: the cloud profile comes from Spring Boot's own CloudFoundryVcapApplicationListener (fires on VCAP_APPLICATION presence), not from anything the buildpack adds — confirmed no such logic exists in src/java/frameworks/spring_auto_reconfiguration.go. The cloud profile is still automatically available regardless of Spring Auto Reconfiguration's enabled state; this section needs correcting.
9. Missing v5 "what's new" / migration notes, incl. Memory Calculator behaviour change — no general "what's new/changed in v5" or migration-warnings page exists, and memory-troubleshooting content still shows a Downloading Open JDK Like Memory Calculator 3.13.0_RELEASE example (Ruby-era version). The Go buildpack ships memory-calculator v4.2.0, which has a behaviour change worth an explicit migration warning:
   • Full breakdown already written up in this repo: RUBY_VS_GO_BUILDPACK_COMPARISON.md §10.2 "Memory Calculator Behaviour Change (v3 → v4)" — should be ported/adapted for docs.cloudfoundry.org.
   • Summary: when an app pins an explicit -Xmx in JAVA_OPTS, v3.13.0 (Ruby) squeezed non-heap memory into whatever remained after -Xmx (non-heap > total check), while v4.2.0 (Go) requires the container to fit both heap and non-heap independently (non-heap + heap > total check). Apps that previously fit in smaller containers under v3 can now fail to start under v4/v5 with an error like required memory 1269289K is greater than 750M available for allocation. When -Xmx is not pinned (recommended), there is no behaviour difference.
   • Migration guidance to include: (1) lower stack_threads if the app uses fewer than 250 threads, (2) remove the pinned -Xmx and let the calculator size heap automatically (may still require raising manifest.yml memory), or (3) increase manifest.yml memory to fit Xmx + non-heap.
   • Good candidate for a dedicated "Upgrading to v5" callout box, since this change can silently break apps at cf push/restage time with no obvious root cause from the error message alone.