[hibernate-dev] Migrating the Migration Guides

[Sanne Grinovero]

On 18 January 2014 13:17, Hardy Ferentschik <hardy at hibernate.org> wrote:
>
> 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.

Ok good idea I'll focus only on the 4 to 5 aspect for now.
Still, at some point I'd like to migrate them 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.
>
> 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?

No need to migrate them now but I see no value in deleting those guides either.
There definitely are many deployments out there using it, at least
just counting my own creations :-)

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

You're probably right on what I'd also do as primary strategy, but as
you also suggest you would fallback to step by step in case of
trouble, and at that point it's handy to have docs.

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

Not sure I follow, as I'm confident you and myself are using the same
approach to major.minor.micro: I guess my own explanation was unclear.
What I meant to highlight is that the structure of our migration
guides should be organized from minor to minor, and in a broader
category major to major, but that the granularity of micro releases is
of less importance.
So that while major migrations could have dedicated pages, and each
minor is probably a section, the strict division between micro
releases is probably of low interest.

I hope we're all on the same page on that so that we can give some
consistent guidelines?

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

thanks!

--Sanne

>
> —Hardy
>
>