The move to Antora means that some links have to change and they are nicely covered by redirects as far as I can see. However, the versioned version uses a two digits format that is very unusual.

The previous arrangement used a three digit format with .x at the end to indicate the "latest" maintenance release of that line, see https://docs.spring.io/spring-framework/docs/6.0.x/reference/html or docs.spring.io/spring-framework/docs/6.0.x-SNAPSHOT/reference/html/

We've had discussions to harmonize the version format and 6.1-SNAPSHOT, in particular, looks really strange. I think we should stick with the format we had for the previous doc and I can't see a reason why we'd want to use something different.

cc @rwinch

Comment From: rwinch

Thanks for the ping @snicoll

I understand that you view the change as "real strange", but I'm curious if there is a concrete problem you are encountering with the new versioned URLs? I believe that the fact that users can now navigate with their mouse using links in the documentation to alternative versions, this is less of a problem that it would have been before.

Just about anything is possible, but changes were discussed within the Spring team (this was part of an initiative announced in an initiative in the All Hands in April 2022) and intentionally made to the URLs. Among the changes/rational are:

  • The current version of the documentation no longer contains a version or alias (e.g. current). This makes the URLs more search engine friendly because search engines tend to favor URLs that have less hierarchy. For example https://docs.spring.io/spring-framework/reference/ will be given priority over https://docs.spring.io/spring-framework/reference/6.1/ because there are more directories in the second URL.
  • We no longer host documentation to every <major>.<minor>.<patch> of the documentation. This is because each version of the documentation is no longer isolated. Factors external to the tag cause the need to update the documentation. Examples include updating the site navigation to include a new project, upon releasing the project a new version needs to be added to the version selector, etc. We can build old versions of the documentation every time this happens, but it becomes slow. Additionally, the builds can become more brittle since we are building a tag that cannot change and the outside environment does. An example of "outside environment" that we have already encountered is that repo.spring.io pruned artifacts and now requires credentials. Another alternative is that we could just no longer link to the older documentation and preserve it, but this means that we have documentation that is inconsistent (and incorrect).
  • Rather than publishing to a URL that has <major>.<minor>.<patch> in it and needing to have redirects, we have decided to omit the .<patch> from the URLs. We could have continued placing .x for patch, but this was something that we intentionally decided to remove while we were cleaning up our URLs. At least in English, when people discuss something that is less precise, they tend to omit it. For example I would say April 2023 if something happened in April. I would not say April X, 2023. Additionally, many popular libraries use URLs of <major>.<minor> with no.x`. A few examples:
  • Javadoc https://docs.oracle.com/javase/8/docs/api/java/net/URL.html
  • Hibernate https://docs.jboss.org/hibernate/orm/6.1/quickstart/html_single/
  • Ruby on Rails https://docs.jboss.org/hibernate/orm/6.1/quickstart/html_single/
  • Python https://docs.python.org/3.11/tutorial/
  • Django https://docs.djangoproject.com/en/4.1/
  • For the same reasons mentioned above with our released documentation, the SNAPSHOT documentation just adds -SNAPSHOT rather than having a .x within the URL. Many projects publish changes to the documentation immediately, but it was decided that we should continue separating our development docs from the released documentation to ensure that in circumstances there were breaking changes both versions of the documentation could exist. This was particularly useful for a milestone that was released and the next SNAPSHOT which might have significant breaking changes.

Comment From: snicoll

Thanks for the feedback.

I believe that the fact that users can now navigate with their mouse using links in the documentation to alternative versions, this is less of a problem that it would have been before.

I don't know what problem you are referring to but this discussion has nothing to do with what a user would do with a mouse. It's about URL format, parsing, automation, and consistency.

Just about anything is possible, but changes were discussed within the Spring team

Sure. Like everything, the devil is in the details so I am not sure why you're bringing this up. Also, thanks for the detailed answer but I don't see how most of it is related to this issue.

We could have continued placing .x for patch, but this was something that we intentionally decided to remove while we were cleaning up our URLs.

Can you please share who is "we"? You're giving the reason why but I am curious if us using <major>.<minor>.x for years means this was the wrong way of doing things? I am not a native speaker so I will defer the reason to you but I question breaking automation and consistency for that reason.

Comment From: rwinch

I don't know what problem you are referring to but this discussion has nothing to do with what a user would do with a mouse. It's about URL format, parsing, automation, and consistency.

Prior to using Antora, users needed to understand what the URL structure was because there were no links. Now users can click on a link to another version rather than understanding the structure of our URLs so that they can edit the URL manually. I believe having links to other versions on the page makes changes to the structure, eg removing the .x, to have less of an impact on users.

Can you please share who is "we"?

It was quite some time ago so I'm not certain who it was but I'd guess that @markpollack @sdeleuze and @Buzzardo participated in discussions around the URL structure. As alluded to previously, the group was formed from an open invite from an All Hands to participate in improving the documentation and so it was determined by those that were interested in participating in the documentation discussions at the time.

You're giving the reason why but I am curious if us using ..x for years means this was the wrong way of doing things? I am not a native speaker so I will defer the reason to you but I question breaking automation and consistency for that reason.

I don't know I'd go as far as calling one approach wrong and another right. However, we knew that we wanted to split up the documentation into more pages, so we knew that the URLs were going to change in some capacity. Given that the URLs were already going to change, we felt the benefits of removing .x outweighed the cons and this was a good time to do it.

Comment From: snicoll

OK, I guess it is what it is and I don't think we'll make much more progress so I am going to close this. Thanks for sharing the context.