Provide migration guides

[mlvandijk]

Proposal: When making large/breaking changes in new versions, provide a migration guide on how to upgrade to the new version.

In general, mention semver versioning (when people can expect breaking changes) and where to find information about (breaking) changes in a new version.

Examples:

• Cucumber-jvm v2: https://cucumber.io/blog/2017/08/29/announcing-cucumber-jvm-2-0-0
  With IntelliJ: The need to upgrade to newer version of Cucumber for Java plugin to prevent error with the Formatter
• For Cucumber-jvm v3; how to update DataTable, how to use Cucumber expressions. (Other?)

[olleolleolle]

Example of other project doing this: Ember.js Deprecations, collected for a release series (2.x): https://www.emberjs.com/deprecations/ember-data/v2.x/

[mlvandijk]

JVM:

• https://cucumber.io/blog/2017/08/29/announcing-cucumber-jvm-2-0-0
• https://cucumber.io/blog/2017/12/05/announcing-cucumber-jvm-2-2-0
• https://cucumber.io/blog/2017/12/11/announcing-cucumber-jvm-2-3-0
• https://cucumber.io/blog/2018/05/19/announcing-cucumber-jvm-3-0-0
• https://cucumber.io/blog/2018/09/24/announcing-cucumber-jvm-4-0-0
• https://cucumber.io/blog/2018/10/31/announcing-cucumber-jvm-4-2-0

[mlvandijk]

See also: cucumber/cucumber-jvm#1478

[mlvandijk]

ElasticSearch has a nice overview of release notes / breaking changes, for example: https://www.elastic.co/guide/en/elasticsearch/reference/current/breaking-changes-6.3.html

[mlvandijk]

This might be helpful: https://stackoverflow.com/questions/54978246/how-to-pass-custom-data-type-to-cucumber-jvm-stepdef-in-latest-4-x-version

[grasshopper7]

ElasticSearch has a nice overview of release notes / breaking changes, for example: https://www.elastic.co/guide/en/elasticsearch/reference/current/breaking-changes-6.3.html

The linked article is 404.

[mlvandijk]

Migration info for deprecated classes (as of cucumber-jvm v4.5.x):

import io.cucumber.junit.CucumberOptions
import io.cucumber.junit.Cucumber
You can replace java8 lambda imports with io.cucumber.java8.En
And java with io.cucumber.java.en.Given
If you run via IDEA change the main class in the run configuration: io.cucumber.core.cli.Main.

[mlvandijk]

@NikolaZag
Please use the support forums for questions and discussions. We use GitHub issues to track bugs and contributions exclusively.

[luke-hill]

We're now doing this in cucumber ruby / jvm and in general are using the repo's proper for more technical docs. So closing this off as completed.