What is required to add a language to the upstream set polyglot

[bbros-dev]

In the upstream docs there are links that render language specific versions of the page.
In this repository these are languages that are part of a polygot set/list.

What is required for a language to have its documentation included upstream as a member of the polygot set/list?

We're contemplating embarking on documenting the cucumber-rust project and would like to do so in a way that allows the Rust documentation to be upstream.
Or at least initially gives us a set of requirements we can cite and target for inclusion upstream.

[luke-hill]

Essentially we use something in our documentation that renders part of the page as "common" and part of the page as language specific.

So if you check out the repo you'll see syntax like this:

{{% text "java,kotlin" %}}
* `message`
* `junit`
* `testng`
{{% /text %}}

This means that the text will only render for the java / kotlin sections.

So to start with you should be able to submit some PR's with a new tag notation for rust. The only other bit we would need to do would be to add the incorporation of that new tag. It's likely that until we incorporate the new tag, it would either not show at all or it would show as plaintext.

To get it activated I would probably defer to @aslakhellesoy or @mlvandijk as the last one we added was Kotlin I believe.

But at least you know now you can start work on some documentation if you so desire.

I hope that helps!

EDIT: To test out the theory of what it would do. If you create a small PR that adds it to one of the pages, we can then preview the page in our CI. This would tell you whether you can add the docs as "invisible" which would probably aide you so we're not a blocker or not.

[bbros-dev]

Thank you for the prompt response. This sounds very promising.

To make sure I understand your response:

1. There are no stability requirements, e.g. pre-1.0 versions are acceptable.
2. There are no completeness/coverage requirements (as above), we assume functionality not implemented should be documented as such.
3. There are no strict compatibility requirements, languages can deviate from one-another as long as the deviation is documented, e.g. cucumber-rust has async and sync steps.
4. There is no requirement to submit all the docs at once, a doc segment can be "invisible", then made visible as a separate step/action.

The workflow we can develop - I'll try to workout the invisible setting.
You're right we don't want to replicate the whole website setup just to inspect correctness. I'll make a small PR and we can see how that works and looks.

[luke-hill]

1. I'm not sure what you mean by this. If a cucumber version is pre 1.0 that is fine. I assume it's a new official maintained project part of the cucumber organisation>?
2. The docs are not equal in measure (They should be), but they're not. Usually what we do where there is a particular functionality undocumented is we put in a placeholder
3. Not really sure I understand this. If you have questions / queries about the codebase, here is not the best place to mention them. (That kind of answers the question 1)
4. Correct - But It has been over a year since we last did this, so I can't remember how we "switched on" kotlin. So submit a PR with a 1line change and a new tag syntax, and netlify will preview it and we can see how it looks. In my head it should just hide nicely and not show. Which means you could do all the changes you want and then we do the magic bit to create the rust section

[bbros-dev]

I'm not sure what you mean by this.
I was trying to work out if you have requirements that a implementation must meet to have its documentation included upstream

1. ... If a cucumber version is pre 1.0 that is fine.
   That is good news - however the maintainer @bbqsrc has decided to hold off "blessing" pushing any docs upstream until they are comfortable with their API stability.

2. .... I assume it's a new official maintained project part of the cucumber organization?

I'm don't know what cucmber.io will maintain and what they won't - they is nothing stopping cucumber Org forking a project to be under its Org and pulling in changes if they want them, and passing on any PR the cucumber Org receives.

I'm working on documenting cucmber-rust in a way that the project doesn't sit siloed from the wider Cucumber community.
With regards to what the Cucumber-Rust maintainer wants to do, perhaps you can elaborate on what is involved in joining cucmber.io and maybe reach-out to @bbqsrc directly? I expect it'll be the same process I just outlined above.

3. Not really sure I understand this. If you have questions / queries about the codebase, here is not the best place to mention them.

Apologies for being unclear.
I have now spent a day on this - instead of building my son and his cousins a game server - so its not a trivial investment of time.... and I have now worked out you have the Cucumber Compatibility Kit (CCK). The CCK document says it can produce a compatibility report - I haven't been able to do that, see Cucumber issue #1400.
In the OP I asked:

What is required for a language to have its documentation included upstream as a member of the polygot set/list?

You gave some instructions about how to add implementation specific code to the user docs. So it appears there is no minimum level of compatibility for an implementation usage docs to be included upstream - or you would have replied to the effect we require x, y, z compatibility, etc.

To avoid confusion I then stated ("To make sure I understand your response"), in 4 points, my understanding of what your response meant.

I have opened Cucumber issue #1400.

4. But It has been over a year since we last did this, so I can't remember how we "switched on" kotlin

No worries. Current and past self are often as distinct as two different people.
@bbqsrc has decided to wait on "blessing" the inclusion of API specific docs, but has accepted PRs working towards having user facing documents included upstream - from a maintainability PoV I would expect there will be only one set of user docs, and these will reside in the broader Cucumber community.

Adding user facing doc to cucmber.io will be an effort that will be incremental and take time so I'll push to the cucumber.io docs site when I can. Yes it would be useful to have a visibility switch.

I'll try to push some small doc change, but I wasted a day not-figuring out the CCK, so it'll have to wait some time.

If there is some need or utility to having cucumber-rust sit under the Cucumber org, just fork it and push any contributions you receive back to @bbqsrc - he raised no objections when I did that, in fact I think that is why he used the licenses he has.

[aslakhellesoy]

We recently discussed this in the weekly community meeting. It's really hard to maintain the current polyglot doc structure, and we're leaning towards abandoning it and pointing users towards implementation-specific documentation in Markdown files on GitHub.

[bbros-dev]

Appreciate the difficulty, and all the work that has gone into cucumber.io.
I wonder if a compromise isn't to require each language to provide code snippets that can be scraped/compiled into the cucumber.io doc's?
Then the criteria of inclusion in cucumber.io is along the lines of: 'The repository containing the cucmber implementation must contain a folder X with files 1...n, containing k. There must be feature file(s) showing each code snippet works.'
Or some such requirements that allows documentation to built and verified as part of CI/CD.
This way each project has to ensure its examples are up to date, and upstream only has to ensure the textual description is generic.

Happy either way happy for this to be closed as you see fit.