You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ignite.apache.org by Vladimir Ozerov <vo...@gridgain.com> on 2018/05/07 08:22:33 UTC
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
Re: Migration guide
Posted by Dmitry Pavlov <dp...@gmail.com>.
+1 from me to approach (co-locating migration guide and main documentation).
пн, 7 мая 2018 г. в 21:00, Denis Magda <dm...@apache.org>:
> 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 <vo...@gridgain.com>
> 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 <is...@apache.org> 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 <vozerov@gridgain.com
> >
> > > 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
> > > >
> > >
> >
>
Re: Migration guide
Posted by Denis Magda <dm...@apache.org>.
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 <vo...@gridgain.com>
wrote:
> Denis,
>
> Sounds good. Could you please share more info about new engine?
>
> пн, 7 мая 2018 г. в 21:00, Denis Magda <dm...@apache.org>:
>
> > 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 <vo...@gridgain.com>
> > 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 <is...@apache.org>
> 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 <
> vozerov@gridgain.com
> > >
> > > > 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
> > > > >
> > > >
> > >
> >
>
Re: Migration guide
Posted by Vladimir Ozerov <vo...@gridgain.com>.
Denis,
Sounds good. Could you please share more info about new engine?
пн, 7 мая 2018 г. в 21:00, Denis Magda <dm...@apache.org>:
> 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 <vo...@gridgain.com>
> 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 <is...@apache.org> 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 <vozerov@gridgain.com
> >
> > > 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
> > > >
> > >
> >
>
Re: Migration guide
Posted by Denis Magda <dm...@apache.org>.
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 <vo...@gridgain.com>
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 <is...@apache.org> 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 <vo...@gridgain.com>
> > 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
> > >
> >
>
Re: Migration guide
Posted by Vladimir Ozerov <vo...@gridgain.com>.
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 <is...@apache.org> 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 <vo...@gridgain.com>
> 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
> >
>
Re: Migration guide
Posted by Igor Sapego <is...@apache.org>.
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 <vo...@gridgain.com>
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
>