Apache Ignite Developers - Legacy Mail Archive

Migration guide

Classic

List

Threaded

7 messages Options

Vladimir Ozerov

Migration guide

Igniters,

We try to maintain API compatibility and keep default behavior unchanged
between minor releases. But as product evolves, some APIs become
deprecated, new best practices appear, and some defaults are changed.

We had a talk with Andrey Gura and he suggested to add *"Migration Guide"*
to our release cycle. This is a document where we will list all important
changes since the last version and our recommendations how to use them. If
done properly this should speedup adoption of new features and migration to
newer versions.

Here are several examples from other vendors:
1) Hibernate -
https://github.com/hibernate/hibernate-orm/wiki/Migration-Guide---5.2
2) Play - https://www.playframework.com/documentation/2.6.x/Migration26

I propose to start creating migration guides since the next release, Apache
Ignite 2.6.

For now let's decide whether community supports this idea, and if yes - how
to publish it. I would propose to do it as follows:
1) Add MIGRATION_GUIDE document next to RELEASE_NOTES. This document should
be updated by contributors during development.
2) After release: publish separate page next to release notes [1]
3) Add links to migration guide to download page [2]

Please share your thoughts.

Vladimir.

[1] https://ignite.apache.org/releases/2.4.0/release_notes.html
[2] https://ignite.apache.org/download.cgi

Igor Sapego-2

Re: Migration guide

Looks like a good idea to me.

But I believe, if we decide to adopt this idea, then we
need to think how to enforce adding notes to migration
guide.

The only way I can currently think of is a pretty obvious
one - adding corresponding instructions to a wiki [1].

Is there anything else we can do here?

[1] - https://cwiki.apache.org/confluence/display/IGNITE/How+to+Contribute

Best Regards,
Igor

On Mon, May 7, 2018 at 11:22 AM, Vladimir Ozerov <[hidden email]>
wrote:

> Igniters,
>
> We try to maintain API compatibility and keep default behavior unchanged
> between minor releases. But as product evolves, some APIs become
> deprecated, new best practices appear, and some defaults are changed.
>
> We had a talk with Andrey Gura and he suggested to add *"Migration Guide"*
> to our release cycle. This is a document where we will list all important
> changes since the last version and our recommendations how to use them. If
> done properly this should speedup adoption of new features and migration to
> newer versions.
>
> Here are several examples from other vendors:
> 1) Hibernate -
> https://github.com/hibernate/hibernate-orm/wiki/Migration-Guide---5.2
> 2) Play - https://www.playframework.com/documentation/2.6.x/Migration26
>
> I propose to start creating migration guides since the next release, Apache
> Ignite 2.6.
>
> For now let's decide whether community supports this idea, and if yes - how
> to publish it. I would propose to do it as follows:
> 1) Add MIGRATION_GUIDE document next to RELEASE_NOTES. This document should
> be updated by contributors during development.
> 2) After release: publish separate page next to release notes [1]
> 3) Add links to migration guide to download page [2]
>
> Please share your thoughts.
>
> Vladimir.
>
> [1] https://ignite.apache.org/releases/2.4.0/release_notes.html
> [2] https://ignite.apache.org/download.cgi
>

Vladimir Ozerov

Re: Migration guide

Igor,

WIKI is the way to go. In addition we are discussing ticket review
guidelines in separate thread at the moment. May be we will be able to
include Migration Guide update there as well.

On Mon, May 7, 2018 at 3:46 PM, Igor Sapego <[hidden email]> wrote:

> Looks like a good idea to me.
>
> But I believe, if we decide to adopt this idea, then we
> need to think how to enforce adding notes to migration
> guide.
>
> The only way I can currently think of is a pretty obvious
> one - adding corresponding instructions to a wiki [1].
>
> Is there anything else we can do here?
>
> [1] - https://cwiki.apache.org/confluence/display/IGNITE/How+to+Contribute
>
> Best Regards,
> Igor
>
> On Mon, May 7, 2018 at 11:22 AM, Vladimir Ozerov <[hidden email]>
> wrote:
>
> > Igniters,
> >
> > We try to maintain API compatibility and keep default behavior unchanged
> > between minor releases. But as product evolves, some APIs become
> > deprecated, new best practices appear, and some defaults are changed.
> >
> > We had a talk with Andrey Gura and he suggested to add *"Migration
> Guide"*
> > to our release cycle. This is a document where we will list all important
> > changes since the last version and our recommendations how to use them.
> If
> > done properly this should speedup adoption of new features and migration
> to
> > newer versions.
> >
> > Here are several examples from other vendors:
> > 1) Hibernate -
> > https://github.com/hibernate/hibernate-orm/wiki/Migration-Guide---5.2
> > 2) Play - https://www.playframework.com/documentation/2.6.x/Migration26
> >
> > I propose to start creating migration guides since the next release,
> Apache
> > Ignite 2.6.
> >
> > For now let's decide whether community supports this idea, and if yes -
> how
> > to publish it. I would propose to do it as follows:
> > 1) Add MIGRATION_GUIDE document next to RELEASE_NOTES. This document
> should
> > be updated by contributors during development.
> > 2) After release: publish separate page next to release notes [1]
> > 3) Add links to migration guide to download page [2]
> >
> > Please share your thoughts.
> >
> > Vladimir.
> >
> > [1] https://ignite.apache.org/releases/2.4.0/release_notes.html
> > [2] https://ignite.apache.org/download.cgi
> >
>

dmagda

Re: Migration guide

Guys,

It's planned to migrate to new documentation engine within 2.6 timeframe,
thus, I would suggest us storing migration guides in Github (together with
doc sources) and publish as a part of the docs on Ignite web site.

What do you think about this approach?

-
Denis

On Mon, May 7, 2018 at 6:20 AM, Vladimir Ozerov <[hidden email]>
wrote:

> Igor,
>
> WIKI is the way to go. In addition we are discussing ticket review
> guidelines in separate thread at the moment. May be we will be able to
> include Migration Guide update there as well.
>
> On Mon, May 7, 2018 at 3:46 PM, Igor Sapego <[hidden email]> wrote:
>
> > Looks like a good idea to me.
> >
> > But I believe, if we decide to adopt this idea, then we
> > need to think how to enforce adding notes to migration
> > guide.
> >
> > The only way I can currently think of is a pretty obvious
> > one - adding corresponding instructions to a wiki [1].
> >
> > Is there anything else we can do here?
> >
> > [1] - https://cwiki.apache.org/confluence/display/IGNITE/How+
> to+Contribute
> >
> > Best Regards,
> > Igor
> >
> > On Mon, May 7, 2018 at 11:22 AM, Vladimir Ozerov <[hidden email]>
> > wrote:
> >
> > > Igniters,
> > >
> > > We try to maintain API compatibility and keep default behavior
> unchanged
> > > between minor releases. But as product evolves, some APIs become
> > > deprecated, new best practices appear, and some defaults are changed.
> > >
> > > We had a talk with Andrey Gura and he suggested to add *"Migration
> > Guide"*
> > > to our release cycle. This is a document where we will list all
> important
> > > changes since the last version and our recommendations how to use them.
> > If
> > > done properly this should speedup adoption of new features and
> migration
> > to
> > > newer versions.
> > >
> > > Here are several examples from other vendors:
> > > 1) Hibernate -
> > > https://github.com/hibernate/hibernate-orm/wiki/Migration-Guide---5.2
> > > 2) Play - https://www.playframework.com/documentation/2.6.x/
> Migration26
> > >
> > > I propose to start creating migration guides since the next release,
> > Apache
> > > Ignite 2.6.
> > >
> > > For now let's decide whether community supports this idea, and if yes -
> > how
> > > to publish it. I would propose to do it as follows:
> > > 1) Add MIGRATION_GUIDE document next to RELEASE_NOTES. This document
> > should
> > > be updated by contributors during development.
> > > 2) After release: publish separate page next to release notes [1]
> > > 3) Add links to migration guide to download page [2]
> > >
> > > Please share your thoughts.
> > >
> > > Vladimir.
> > >
> > > [1] https://ignite.apache.org/releases/2.4.0/release_notes.html
> > > [2] https://ignite.apache.org/download.cgi
> > >
> >
>

Vladimir Ozerov

Re: Migration guide

Denis,

Sounds good. Could you please share more info about new engine?

пн, 7 мая 2018 г. в 21:00, Denis Magda <[hidden email]>:

> Guys,
>
> It's planned to migrate to new documentation engine within 2.6 timeframe,
> thus, I would suggest us storing migration guides in Github (together with
> doc sources) and publish as a part of the docs on Ignite web site.
>
> What do you think about this approach?
>
> -
> Denis
>
> On Mon, May 7, 2018 at 6:20 AM, Vladimir Ozerov <[hidden email]>
> wrote:
>
> > Igor,
> >
> > WIKI is the way to go. In addition we are discussing ticket review
> > guidelines in separate thread at the moment. May be we will be able to
> > include Migration Guide update there as well.
> >
> > On Mon, May 7, 2018 at 3:46 PM, Igor Sapego <[hidden email]> wrote:
> >
> > > Looks like a good idea to me.
> > >
> > > But I believe, if we decide to adopt this idea, then we
> > > need to think how to enforce adding notes to migration
> > > guide.
> > >
> > > The only way I can currently think of is a pretty obvious
> > > one - adding corresponding instructions to a wiki [1].
> > >
> > > Is there anything else we can do here?
> > >
> > > [1] - https://cwiki.apache.org/confluence/display/IGNITE/How+
> > to+Contribute
> > >
> > > Best Regards,
> > > Igor
> > >
> > > On Mon, May 7, 2018 at 11:22 AM, Vladimir Ozerov <[hidden email]
> >
> > > wrote:
> > >
> > > > Igniters,
> > > >
> > > > We try to maintain API compatibility and keep default behavior
> > unchanged
> > > > between minor releases. But as product evolves, some APIs become
> > > > deprecated, new best practices appear, and some defaults are changed.
> > > >
> > > > We had a talk with Andrey Gura and he suggested to add *"Migration
> > > Guide"*
> > > > to our release cycle. This is a document where we will list all
> > important
> > > > changes since the last version and our recommendations how to use
> them.
> > > If
> > > > done properly this should speedup adoption of new features and
> > migration
> > > to
> > > > newer versions.
> > > >
> > > > Here are several examples from other vendors:
> > > > 1) Hibernate -
> > > >
> https://github.com/hibernate/hibernate-orm/wiki/Migration-Guide---5.2
> > > > 2) Play - https://www.playframework.com/documentation/2.6.x/
> > Migration26
> > > >
> > > > I propose to start creating migration guides since the next release,
> > > Apache
> > > > Ignite 2.6.
> > > >
> > > > For now let's decide whether community supports this idea, and if
> yes -
> > > how
> > > > to publish it. I would propose to do it as follows:
> > > > 1) Add MIGRATION_GUIDE document next to RELEASE_NOTES. This document
> > > should
> > > > be updated by contributors during development.
> > > > 2) After release: publish separate page next to release notes [1]
> > > > 3) Add links to migration guide to download page [2]
> > > >
> > > > Please share your thoughts.
> > > >
> > > > Vladimir.
> > > >
> > > > [1] https://ignite.apache.org/releases/2.4.0/release_notes.html
> > > > [2] https://ignite.apache.org/download.cgi
> > > >
> > >
> >
>

Dmitriy Pavlov

Re: Migration guide

In reply to this post by dmagda

+1 from me to approach (co-locating migration guide and main documentation).

пн, 7 мая 2018 г. в 21:00, Denis Magda <[hidden email]>:

dmagda

Re: Migration guide

In reply to this post by Vladimir Ozerov

Vladimir,

Here is you can find a short summary on the planned migration:
https://issues.apache.org/jira/browse/IGNITE-7595

This discussion goes with more details:
http://apache-ignite-developers.2346864.n4.nabble.com/Move-documentation-from-readme-io-to-GitHub-pages-td16409.html

--
Denis

On Mon, May 7, 2018 at 12:22 PM, Vladimir Ozerov <[hidden email]>
wrote:

> Denis,
>
> Sounds good. Could you please share more info about new engine?
>
> пн, 7 мая 2018 г. в 21:00, Denis Magda <[hidden email]>:
>
> > Guys,
> >
> > It's planned to migrate to new documentation engine within 2.6 timeframe,
> > thus, I would suggest us storing migration guides in Github (together
> with
> > doc sources) and publish as a part of the docs on Ignite web site.
> >
> > What do you think about this approach?
> >
> > -
> > Denis
> >
> > On Mon, May 7, 2018 at 6:20 AM, Vladimir Ozerov <[hidden email]>
> > wrote:
> >
> > > Igor,
> > >
> > > WIKI is the way to go. In addition we are discussing ticket review
> > > guidelines in separate thread at the moment. May be we will be able to
> > > include Migration Guide update there as well.
> > >
> > > On Mon, May 7, 2018 at 3:46 PM, Igor Sapego <[hidden email]>
> wrote:
> > >
> > > > Looks like a good idea to me.
> > > >
> > > > But I believe, if we decide to adopt this idea, then we
> > > > need to think how to enforce adding notes to migration
> > > > guide.
> > > >
> > > > The only way I can currently think of is a pretty obvious
> > > > one - adding corresponding instructions to a wiki [1].
> > > >
> > > > Is there anything else we can do here?
> > > >
> > > > [1] - https://cwiki.apache.org/confluence/display/IGNITE/How+
> > > to+Contribute
> > > >
> > > > Best Regards,
> > > > Igor
> > > >
> > > > On Mon, May 7, 2018 at 11:22 AM, Vladimir Ozerov <
> [hidden email]
> > >
> > > > wrote:
> > > >
> > > > > Igniters,
> > > > >
> > > > > We try to maintain API compatibility and keep default behavior
> > > unchanged
> > > > > between minor releases. But as product evolves, some APIs become
> > > > > deprecated, new best practices appear, and some defaults are
> changed.
> > > > >
> > > > > We had a talk with Andrey Gura and he suggested to add *"Migration
> > > > Guide"*
> > > > > to our release cycle. This is a document where we will list all
> > > important
> > > > > changes since the last version and our recommendations how to use
> > them.
> > > > If
> > > > > done properly this should speedup adoption of new features and
> > > migration
> > > > to
> > > > > newer versions.
> > > > >
> > > > > Here are several examples from other vendors:
> > > > > 1) Hibernate -
> > > > >
> > https://github.com/hibernate/hibernate-orm/wiki/Migration-Guide---5.2
> > > > > 2) Play - https://www.playframework.com/documentation/2.6.x/
> > > Migration26
> > > > >
> > > > > I propose to start creating migration guides since the next
> release,
> > > > Apache
> > > > > Ignite 2.6.
> > > > >
> > > > > For now let's decide whether community supports this idea, and if
> > yes -
> > > > how
> > > > > to publish it. I would propose to do it as follows:
> > > > > 1) Add MIGRATION_GUIDE document next to RELEASE_NOTES. This
> document
> > > > should
> > > > > be updated by contributors during development.
> > > > > 2) After release: publish separate page next to release notes [1]
> > > > > 3) Add links to migration guide to download page [2]
> > > > >
> > > > > Please share your thoughts.
> > > > >
> > > > > Vladimir.
> > > > >
> > > > > [1] https://ignite.apache.org/releases/2.4.0/release_notes.html
> > > > > [2] https://ignite.apache.org/download.cgi
> > > > >
> > > >
> > >
> >
>