Update CONTRIBUTING guide#72
Open
mpkorstanje wants to merge 1 commit into
Open
Conversation
* Add AI usage policy * Add Project organization
olleolleolle
reviewed
Jun 2, 2026
| └── testdata # test data for acceptance tests | ||
| ``` | ||
|
|
||
| Generally speaking, each implementation can be build independently of the |
Contributor
There was a problem hiding this comment.
Suggested change
| Generally speaking, each implementation can be build independently of the | |
| Generally speaking, each implementation can be built independently of the |
olleolleolle
reviewed
Jun 2, 2026
| ### Monoglot | ||
|
|
||
| If the repository you're looking at doesn't look like a polyglot repo it | ||
| probably is for a single language. In this case it can probably be build using |
Contributor
There was a problem hiding this comment.
Suggested change
| probably is for a single language. In this case it can probably be build using | |
| probably is for a single language. In this case it can probably be built using |
olleolleolle
reviewed
Jun 2, 2026
olleolleolle
left a comment
olleolleolle
left a comment
Contributor
There was a problem hiding this comment.
Good to have clarity!
luke-hill
reviewed
Jun 2, 2026
luke-hill
left a comment
luke-hill
left a comment
Contributor
There was a problem hiding this comment.
Popped in a bunch of minor tweaks. Take as many/few as you think are appropriate.
| ## AI Usage | ||
|
|
||
| Cucumber is developed and maintained by humans. We read every discusison, issue | ||
| and pull reqeust. As such we appreciate it if you take the time to communicate |
Contributor
There was a problem hiding this comment.
Suggested change
| and pull reqeust. As such we appreciate it if you take the time to communicate | |
| and pull request. As such we appreciate it, if you would take time to communicate with us. |
Member
There was a problem hiding this comment.
I think the original wording was fine, but we could elaborate a bit, because I think we mostly mean:
- Issues and pull requests must follow the template and be in your own words
- Comments in issues and pull requests must be in your own words
- If we get the sense that we're just conversing with a bot, we'll stop
(But less adversarial sounding.)
|
|
||
| Cucumber is developed and maintained by humans. We read every discusison, issue | ||
| and pull reqeust. As such we appreciate it if you take the time to communicate | ||
| with us. |
Contributor
There was a problem hiding this comment.
Suggested change
| with us. |
| AI-assisted. | ||
| * **You must fully understand all code.** | ||
| You should be able to explain what your changes do and how they interact with | ||
| the greater system without the aid of AI tools. |
Contributor
There was a problem hiding this comment.
Suggested change
| the greater system without the aid of AI tools. | |
| the wider ecosystem without the aid of AI tools. This is important because as maintainers, we need to ensure that the changes made to the codebase are not prohibitive of further development later on - plus we need to ensure that the code does indeed do what it sets out to! |
| * **You must fully understand all code.** | ||
| You should be able to explain what your changes do and how they interact with | ||
| the greater system without the aid of AI tools. | ||
| * **You must be in the loop**. |
Contributor
There was a problem hiding this comment.
Suggested change
| * **You must be in the loop**. | |
| * **You must be in control - the final part of the process**. |
| the greater system without the aid of AI tools. | ||
| * **You must be in the loop**. | ||
| Any content generated with AI must have been reviewed and edited by you | ||
| (a human) before submission. |
Contributor
There was a problem hiding this comment.
Suggested change
| (a human) before submission. | |
| (a human), before you submit it to us as a PR. Self review is important! |
| ## Project organization | ||
|
|
||
| _Note: This is the catch-all contributing guide and not all repositories are | ||
| organized the same. So this guide can't help you with the specifics. The |
Contributor
There was a problem hiding this comment.
Suggested change
| organized the same. So this guide can't help you with the specifics. The | |
| organized the same. So this guide won't help you with anything specific. The |
|
|
||
| ### Polyglot | ||
|
|
||
| Polyglot repositories contains identical implementations of a component in |
Contributor
There was a problem hiding this comment.
Suggested change
| Polyglot repositories contains identical implementations of a component in | |
| Polyglot repositories contain near-identical implementations of one part of the cucumber ecosystem in |
|
|
||
| If the repository you're looking at doesn't look like a polyglot repo it | ||
| probably is for a single language. In this case it can probably be build using | ||
| the tools typical for that language. If you don't know what those are then |
Contributor
There was a problem hiding this comment.
Suggested change
| the tools typical for that language. If you don't know what those are then | |
| the tools typical for that language. If you don't know what those are then |
| If the repository you're looking at doesn't look like a polyglot repo it | ||
| probably is for a single language. In this case it can probably be build using | ||
| the tools typical for that language. If you don't know what those are then | ||
| again `.github/workflows/test-<language>.yaml` would be a good place to start. |
Contributor
There was a problem hiding this comment.
Suggested change
| again `.github/workflows/test-<language>.yaml` would be a good place to start. | |
| again, looking at `.github/workflows/test-<language>.yaml` would be the first suggestion. |
davidjgoss
reviewed
Jun 2, 2026
|
|
||
| When you use AI, we require that you do the following: | ||
|
|
||
| * **All AI usage in any form must be disclosed** |
Member
There was a problem hiding this comment.
This kind of detailed disclosure requirement seems draconian to me, and I'm not sure what signal we're hoping to get from someone saying they used e.g. Cursor vs Claude Code, or to what degree or in what style.
If we want a disclosure I think adding to the checklist on the PR template would be a decent start, like:
- [ ] I used AI tool(s) in the making of this pull request
- [ ] I have reviewed, understand and can converse about every line in the diff(And of course if they don't use the template, you have the answer.)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🤔 What's changed?
⚡️ What's your motivation?
GitHub shows the default contributing guide in places where we have none. Which is quite a few repositories. The current guide is motivating but not very helpful.
Additionally I want to highlight that people should use AI responsibly. The guide lines are mostly inspired by those of Ghostty. But reworded to be a little bit friendlier.
🏷️ What kind of change is this?
♻️ Anything particular you want feedback on?
Agree, disagree? Anything missing?
📋 Checklist: