BC in keywords

[ciaranmcnulty]

Cucumber is advancing their major versions pretty fast, they're on 16.0.0

They're ok about keeping semver as far as keywords are concerned, but we are blindly consuming those translations within the 4.x line

What to do? Do we make a new major every time cucumber does?

[ciaranmcnulty]

The obvious thing to do I guess would be to continually bump the major version number, but then behat would need to keep doing the same

Another would be to somehow split out the keywords into a separate repository?

[stof]

Another would be to somehow split out the keywords into a separate repository?

that would not help either. If behat/gherkin is the one depending on behat/gherkin-keywords, changing the constraint to allow a new major version of behat/gherkin-keywords would still break projects using behat/gherkin if they rely on a removed keyword (as they probably won't directly depend on behat/gherkin-keywords).

[ciaranmcnulty]

But we could version they keywords similarly to the cucumber versions, and at least when there was a break people would be able to pin back to an older version explicitly

Or we could make gherkin-keywords just a suggest, and throw an exception if it's not present?

[stof]

if gherkin-keywords is an optional dependency of gherkin that gets managed separately in projects using i18n, this would indeed solve this.
If we go this way, I would still include the en locale in behat/gherkin itself so that things work out of the box for projects not using i18n in their gherkin files. If we only need to manage BC breaks in the en keywords, it should be fine (they probably don't break the existing en keywords in each of their major releases, and we will be able to review such changes)

[ciaranmcnulty]

@aslakhellesoy Can you comment on the likelihood of breaking backwards compatibility in the en translation of gherkin?

We'd need to communicate to users why their tests stopped working if we went this route, of course

[ciaranmcnulty]

@stof we could even call it something like gherkin-i18n in that case

[stof]

@ciaranmcnulty indeed. even better.

If we go that way, I suggest consider #203 first (that I just created) as behat/gherkin-i18n would then ship in the new format.

[ciaranmcnulty]

On the other hand maybe we could make cucumber/gherkin-php that only contains the translations (and the Dialect objects?) and gets versioned with the monorepo

[stof]

That would not help if behat/gherkin is the one depending on it rather than the project bringing it.
The available translation keywords are part of the public API of a gherkin parser (removing a keyword would make your existing gherkin file invalid if it was using the keyword), so updating to a newer major version of cucumber/gherkin-php would be a BC break for behat/gherkin as projects would receive the new keywords without any other opt-in. And so it would still require new major versions of behat/gherkin.

To me, we have only 3 solutions:

1. bump the major version of behat/gherkin each time cucumber bumps the gherkin major version (or at least each time it bumps it due to keyword-related BC breaks as we only care about their translations, not about other APIs)
2. create a separate behat/gherkin-i18n package that projects require, so they can choose when the migrate to the new BC-breaking keywords. In this option, behat/gherkin would require a major version only in case of BC break in the English keywords (we must still ship support for English in behat/gherkin otherwise the package is unusable without using behat/gherkin-i18n, which would then justify making behat/gherkin-i18n a requirement, and then we're back at option 1)
3. not caring about BC breaks in translation updates, shipping them in behat/gherkin minor versions (i.e. the current state, except that we were not really updating at all in the past 2 years instead)

[ciaranmcnulty]

Whatever strategy we took for 2. would also apply to a cucumber/gherkin-php wouldn't it? We'd need some mechanism (a break?) that prompted projects to directly depend on the new package

[stof]

@ciaranmcnulty if behat/gherkin has a requirement on cucumber/gherkin-php, then there is nothing enforcing projects to directly depend on them.
That's why my suggestion for 2. is still bundling the English keywords in the main package, so that the parser can still be used (for non-i18n gherkin file) by default, even if behat/gherkin does not depend on behat/gherkin-i18n. This solves this issue as a project wanting to parse i18n gherkin files has to depend on the i18n package directly (as nothing else depends on it).
Of course, we would still need a major version bump of behat/gherkin initially when removing support for i18n without the dedicated package.

And the fact that English is usable without the i18n package also implies that the dialect classes are still part of behat/gherkin. The behat/gherkin-i18n package would only provide the translations, not the infrastructure for dealing with a gherkin dialect.

then, having this translation-only package being named behat/gherkin-i18n or cucumber/gherkin-php is just a naming thing. but I would prefer avoiding the cucumber/gherkin-php name for a package shipping only gherkin translations in a composer package. The package name would imply that it is the PHP parser for Gherkin. And that would block the name if we later decide to implement a PHP parser in the monorepo (based on the cucumber generated parsers), while that cucumber/gherkin-php name would be the perfect match for such parser.

[ciaranmcnulty]

The obvious thing to do I guess would be to continually bump the major version number, but then behat would need to keep doing the same

Having considered the options I'm leaning towards this. It doesn't hurt much if Behat/Gherkin has a lot of releases, and it's trivial to increase the supported versions in Behat/Behat (in a patch release?) Then users can pin back their Gherkin version if they want to.

[acoulton]

Now that we're going to start pulling cucumber/gherkin updates again I guess we'll need to consider this.

I'd ideally want to avoid having lots of major releases of this package all in active use. Although it's not too complex to do, there would be downsides:

• It'd be an extra bit of work for maintainers on an ongoing basis to check whether translations have changed, bump the version in this package (e.g. the composer branch-alias) and then update Behat to support it
• We'd have to decide how many of the "supported" versions we cover in Behat's CI - just the lowest and latest, or one of each series?
• It could be tricky to work out how to target unrelated bugfixes and enhancements. We don't really want to have to maintain multiple major version branches and deal with merging up and releasing points of each one. But is it reasonable to prevent people getting updates unless they manually change the wording of their feature files and bump to the latest major (probably not...)?

Splitting the translations to a separate package feels like possibly a better solution for the long term.

For the short term, if I've understood correctly, couldn't we just merge new translations from gherkin rather than replacing them? We are (I think) only using these to recognise keywords in people's feature files, so as long as we recognise strings that were valid with older gherkin versions and the most recent transalations, there's no problem?