| I have noticed a few spots in the documentation where we link to specific doc urls on the doc server via the 'stable' url scheme. I think that is a bad idea. We decided that 'stable/orm' will always point to 'orm/current'. For the time being when 5.1 is the only version involved this is not such a big deal. However let's fast-forward to post-6.0 release and consider a problematic case... As an example, see http://docs.jboss.org/hibernate/orm/5.1/userguide/html_single/Hibernate_User_Guide.html#bootstrap-native-metadata. Here there is a link to some javadoc at https://docs.jboss.org/hibernate/stable/orm/javadocs/org/hibernate/boot/MetadataSources.html#buildMetadata-- (extra dashes at end not mine). Now let's say that we release 6.0 and remove that method. The 6.0 version of the User Guide gets updated and it works fine. However, the 5.1 version of the User Guide is "still/now" pointing to 'stable/orm' -> 'orm/current', which now means 6.0. However that javadoc link is invalid now. I think we should discuss proper ways to deal with this, whether that be in the form of:
- relative references (based on doc server arrangement)
- explicit inclusion of the version major.minor into these URLs (the doc build already knows the version)
- other?
|