docs: Upgrade guide for v4.0.0

[skyqrose]

I'm attempting to upgrade from 3.3.3 to 4.0.0, which has major breaking changes. The Changelog gives instructions for adding a new dependency to maintain compatibility.

v4.0.0 (2023-12-19)

This version removes deprecated functionality and moved all HTML helpers to a separate library. HTML Helpers are no longer used in new apps from Phoenix v1.7. Older applications who wish to maintain compatibility, add {:phoenix_html_helpers, "~> 1.0"} to your mix.exs and then replace use Phoenix.HTML in your applications by:

import Phoenix.HTML
import Phoenix.HTML.Form
use PhoenixHTMLHelpers

But presumably the breaking change was made for good reasons, and I'd rather upgrade my code to the new API than keep the old code forever. There's no instructions for how to do that, and no docs for what the differences between the old and new systems are. Can someone write those and include them in the changelog?

[josevalim]

Using the old code is fine, it is still maintained.

In a nutshell, we removed a bunch of functions and modules. Those are now in PhoenixHTMLHelpers. You can either rewrite your code to not use them (by writing the markup by hand) or use the dependency. PRs to the CHANGELOG are welcome.