Branching strategy

[rossabaker]

Wanted to jot some notes down for future maintainers.

These http4s-$BLAH repos are usually an integration between http4s-core and $BLAH. http4s-core and $BLAH may operate on separate release cycles, so it is advantageous to put them in separate repositories. (There are more pros and cons, but that's a longer post.)

General branching

In January 2023, we are actively maintaining http4s-core-0.23 and developing http4s-core-1.0. Most of these ancillary repositories will thus have a series/0.23 and a main branch. When $BLAH makes a breaking change before http4s, we usually bump the minor version: http4s-blah-0.24, http4s-blah-0.25, etc. http4s-blah-0.x always targets http4s-core-0.23, but we can support the latest $BLAH without breaking the entire http4s ecosystem. We figure http4s-core-1.x users live on the bleeding edge, and typically only support the latest $BLAH there.

Servlets

Life is more complicated in the Servlet ecosystem, because multiple versions of Servlet (and their containers) are considered production ready.

• http4s-servlet-0.23 supports Servlet 3.1, because that's what was production ready when http4s-0.23 was released.
• http4s-servlet-0.24 supports Servlet 4. It's not really that compelling for us! It does introduce HttpFilter, which is a nice cleanup, but hardly anybody uses Filter with http4s anyway! I think we could run http4s-servlet-0.23 code on a Servlet 4 container and been just fine.
• http4s-servlet-0.25 supports Servlet 5. This is just a rename of Servlet 4's javax to jakarta, which breaks everything, but I believe it's where most modern Servlet development is happening.
• There's a Servlet 6 hot off the presses, which is backward incompatible because it removes a bunch of deprecated methods. http4s-servlet doesn't support this yet. I didn't really want to maintain 4 http4s-core-0.23 branches for a repo with single digit stars, you know?
• http4s-servlet-1.0 milestones are currently packaging Servlet 5 for http4s-core-1.0.

Tomcat

• http4s-tomcat-0.23 is published against http4s-servlet-0.23 and Tomcat 9 (which supports up to Servlet 4).
• http4s-tomcat-0.24 was necessary to deal with HttpFilter, but like Servlet 4, wasn't that interesting.
• http4s-tomcat-0.25 gets us to Servlet 5 and Tomcat 10.0.
• Now there's Tomcat 10.1 for Servlet 6, which I don't think was production ready last time I looked at this.

Conjecture

I don't think anybody cares about Servlet 4. I don't think many people care about Servlet 5 on http4s. If you're still reading, you care about Servlets in general on http4s. Maybe we proud few should just focus on Servlet 6 support in the year 2023? Those milestones are there if anybody needs them... and they can contribute labor if they do.