[hibernate-dev] Migrating the Migration Guides

[Sanne Grinovero]

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