[hibernate-dev] Migrating the Migration Guides

[Hardy Ferentschik]

On 18 Jan 2014, at 12:12, Sanne Grinovero <sanne at hibernate.org> wrote:

> 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 agree, we probably should add the migration guides to the site.
However, I am not a big fan of the existing ones and just migrating them.
I think they are badly structured. I would consider leaving the existing guides 
where they are (at least for now) and just start with a 4 to 5 migration. You 
can always add a link to the old guide.

Another benefit is that you don’t waste time migration the guides and can focus
directly what you want to do.

> 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.

If you want to migrate, it should for sure be split. As I mentioned above I
would not bother for now with a migration, or it at all only migrate the latest changes.

> - Migrating from Hibernate Search 3.x to Hibernate Search 4.x
> - Minor upgrade hints across Hibernate Search 3.x versions

Do we still need that? 

> 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.

Probably not what I would do. If I want go to the version I want to use first.
Only if I would face major problems I would back step. I don’t think that many
people would do this incremental approach. Obviously that’s my opinion,
but at least it shows that there are different approaches to this. 

> 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

I exlude myself here.

> Could someone more familiar with the website details please structure
> the base layout for this? 

It should be straight forward. Create a directory called ‘migration’ and and a index.adoc.
Edit site.yml and add a new intern link. You can start with doing this just for Search or apply
this already to all projects. index.adoc can be the general page you are talking about. Just place
additional migration guides into the same directory. I don’t think there is more to it. If in the end there
is something which we want to add to each project we can extract a partial at a alter stage.

—Hardy