Re: [hibernate-dev] Migrating the Migration Guides
On 18 Jan 2014, at 12:12, Sanne Grinovero <sanne(a)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