[hibernate-dev] Migrating the Migration Guides

The new website is missing the migration guides; specifically I'm looking at Hibernate Search but since we probably want to keep a familiar structure across the various projects, I hope to get feedback from all. I'd like to move the Search migration guide from the jboss.org Wiki to ascidoc, but also it has become quite large and I think it should be split in different pages. I'd expect to see a "Migration" landing page for Search, beginning with two lines of text for general advice, to then point to: - Migrating from Hibernate Search 4.x to Hibernate Search 5.x - Minor upgrade hints across Hibernate Search 4.x versions - Migrating from Hibernate Search 3.x to Hibernate Search 4.x - Minor upgrade hints across Hibernate Search 3.x versions We probably want to suggest users to always migrate in steps of minor versions, but skipping the micro versions. For example if I'm updating an Hibernate Search 4.3.0.Final, I'd bump my dependency to 4.4.2.Final as a first step, apply some changes as suggested by the guides, run the tests, then jump again as needed. My reasoning to suggest skip the micro versions is dual-fold: - we're not supposed to break any API in that range anyway, so going through the micro hops is probably a waste of time - in case we screw up with some bug in the first release of a minor, that would make a migration harder (failing tests) and we should be correcting this with micro versions so the latest micro is what people are supposed to use to avoid this bug I guess we're all on the same page as general guidelines? I think this sounds very familiar to us as we are used to this approach but it's worthwhile to explain as occasional users might be used to different conventions or have a different understanding of versions. Could someone more familiar with the website details please structure the base layout for this? Like if we could agree quickly on the shape of the menu, I will then migrate the content for Search. N.B. I have a lot to write down urgently for the migration to Search 5 guide: I think we'll be releasing a first preview next week and these docs should be in place. If that doesn't work out I can of course write it in the existing wiki. Sanne