-
-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Improvement of welcoming documentation (#1542)
* Update README.md * Update gherkin example image * Update README documentation and support section * Update README with *a lot of* other languages * Introduce other languages earlier in the README * Rewrite contributting document [skip ci] This is still eavily wip. * Add more info to CONTRIBUTING doc [skip ci] * Fix some typos in CONTRIBUTING.md [skip ci] * Add more info to CONTRIBUTING.md [skip ci] * Add more info in contributing.md * Add info on how to open a good issue in contributing * [skip ci]Add description of development environment in contributing * [skip ci]Add more info to contributing#development-environment * [skip ci] Add Gemfile.local info into CONTRIBUTING * [skip ci]Extract release process from contributing * [skip ci] Add a chatper dedicated to Cucumber-ruby-core * [skip ci]Update PR Template * [skip ci]Add info about full-time maintainers * Tweaks during review * Hyperlink to other cucumber flavours * Highlight CoC with its own paragraph Co-authored-by: Matt Wynne <matt@cucumber.io>
- Loading branch information
1 parent
68cd3ae
commit 3c34ec1
Showing
6 changed files
with
406 additions
and
70 deletions.
There are no files selected for viewing
This file contains 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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,9 +1,43 @@ | ||
**Is your pull request related to a problem? Please describe.** | ||
# Description | ||
|
||
A link to an issue or a clear and concise description of what the problem is. Ex. I'm always frustrated when [...] | ||
Please include a summary of the change, mentioning any issues that are fixed (or partially fixed) by this change. | ||
|
||
**Describe the solution you have implemented** | ||
A clear and concise description of what happens. | ||
Please also include relevant motivation and context. | ||
|
||
**Additional context** | ||
Add any other context or screenshots about the pull request here. | ||
e.g. "Fixes #99" | ||
|
||
## Type of change | ||
|
||
Please delete options that are not relevant. | ||
|
||
- Refactoring (improvements to code design or tooling that don't change behaviour) | ||
- Bug fix (non-breaking change which fixes an issue) | ||
- New feature (non-breaking change which adds new behaviour) | ||
- Breaking change (will cause existing functionality to not | ||
work as expected) | ||
- This change requires an update of [cucumber.io/docs](https://cucumber.io/docs) | ||
|
||
Please add an entry to the relevant section of CHANGELOG.md as part of this pull request. | ||
|
||
## Note to other contributors | ||
|
||
If your change may impact future contributors, explain it here, and remember to update README.md and CONTRIBUTING.md accordingly. | ||
|
||
## Update required of cucumber.io/docs | ||
|
||
If the [Cucumber documentation](https://cucumber.io/docs/) requires an update, | ||
submit a PR to [cucumber/docs](https://github.com/cucumber/docs/) and | ||
reference it here. | ||
|
||
e.g. "Ref: cucumber/docs/pull/#99" | ||
|
||
# Checklist: | ||
|
||
Your PR is ready for review once the following checklist is | ||
complete. You can also add some checks if you want to. | ||
|
||
- [ ] Tests for any changes to behaviour of the code | ||
- [ ] New and existing tests are passing locally and on CI | ||
- [ ] `bundle exec rubocop` reports no offenses | ||
- [ ] RDoc comments have been updated | ||
- [ ] CHANGELOG.md has been updated |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains 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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,85 +1,243 @@ | ||
## About to create a new Github Issue? | ||
# Contributing to Cucumber | ||
|
||
We appreciate that. But before you do, please learn our basic rules: | ||
Thank you for considering contributing to Cucumber! | ||
|
||
- This is not a support forum. If you have a question, please go to [The Cukes Google Group](http://groups.google.com/group/cukes). | ||
- Do you have an idea for a new feature? Then don't expect it to be implemented unless you or someone else sends a [pull request](https://help.github.com/articles/using-pull-requests). You might be better to start a discussion on [the google group](http://groups.google.com/group/cukes). | ||
- Reporting a bug? Please tell us: | ||
- which version of Cucumber you're using | ||
- which version of Ruby you're using. | ||
- How to reproduce it. Bugs with a failing test in a [pull request](https://help.github.com/articles/using-pull-requests) get fixed much quicker. Some bugs may never be fixed. | ||
- Want to paste some code or output? Put \`\`\` on a line above and below your code/output. See [GFM](https://help.github.com/articles/github-flavored-markdown)'s _Fenced Code Blocks_ for details. | ||
- We love [pull requests](https://help.github.com/articles/using-pull-requests). But if you don't have a test to go with it we probably won't merge it. | ||
This document will first introduce different ways to get involved before | ||
focusing on how to contribute to the code. | ||
|
||
# Contributing to Cucumber | ||
## Code of Conduct | ||
|
||
Everyone interacting in this codebase and issue tracker is expected to follow | ||
the Cucumber [code of conduct](https://cucumber.io/conduct). | ||
|
||
## How can I contribute? | ||
|
||
If you read this, you are certainly looking to contribute to the code. Cucumber | ||
is not this single repository. It is made up of several packages around several | ||
repositories. So before going further with the code, you may consider the | ||
following first, in order to get your bearings. | ||
|
||
If you just want to know how to contribute to the code, go to | ||
[Contribute to the code](#contribute-to-the-code). | ||
|
||
If you want to report an issue, or suggest an enhancement, go to | ||
[Report bugs and submit feature requests](#report-bugs-and-submit-feature-requests). | ||
|
||
### Meet the community, the maintainers, and other Cucumber developers | ||
|
||
Smartbear is hosting a [community message board]. | ||
This is a good place to meet users, the community, and to ask questions. | ||
|
||
You can also join the Cucumber Community Slack team: | ||
[register for an account][register-slack] then head over to [#intro][slack-intro]. | ||
This is the place to be to meet the maintainers aka the core team. | ||
|
||
### Test Cucumber | ||
|
||
Testing Cucumber, especially new features, is a great way to contribute. We | ||
cannot put a price on (early) feedback. | ||
|
||
Keep an eye on our CHANGELOGS to discover new features. Test and experiment, and | ||
submit your feedback through [issues](#report-bugs-and-submit-feature-requests), | ||
the [community message board], or [Slack][community-slack]. | ||
|
||
### Contribute to the documentation | ||
|
||
[The documentation][cucumber-docs] is an important part of Cucumber. It is | ||
essential that it remains simple and accurate. You can contribute to it via | ||
[github.com/cucumber/docs](https://github.com/cucumber/docs). | ||
|
||
### Promote Cucumber | ||
|
||
You don't know how to contribute but would like to help? Telling other people | ||
about Cucumber on the Internet - social media, reviews, blogs - but also in real | ||
life is already a big help! Join us on [Slack][community-slack] to share your | ||
publication and to discover new ones. | ||
|
||
## Report bugs and submit feature requests | ||
|
||
The short version is: | ||
|
||
- Find the appropriate repository | ||
- Make sure there is not already an issue or pull request that deals with your | ||
bug or request | ||
- Consider submitting a pull request if you feel confident enough | ||
- Explain your issue and include as much details as possible to help other | ||
people reproduce your problem or understand your request | ||
|
||
You can find more details for each of these steps in the following sections. | ||
|
||
### Find the appropriate repository | ||
|
||
The current repository, `cucumber-ruby`, is actually the tip of the iceberg. It | ||
provides a user interface through a CLI, some built-in formatters, and the | ||
execution environment you may know as the `World` object. | ||
|
||
An important repository is [cucumber/common]. It is a mono-repo | ||
with a lot of libraries. You will find there what is related to: | ||
|
||
- parsing Gherkin documents - aka `.feature` files | ||
- parsing tag expressions - the options you use to filter an execution with tags | ||
- parsing Cucumber expressions - the expressions that link a Gherkin step to a | ||
step definition | ||
- everyting related to the HTML formatter | ||
|
||
`cucumber-ruby` is also composed of: | ||
|
||
- [cucumber-ruby-core]: this is the engine that will execute the test cases | ||
computed from a parsed Gherkin document | ||
- [cucumber-ruby-wire]: everything related to the Cucumber's wire protocol | ||
|
||
Last but not least, there is also a repository for [cucumber-rails], the gem | ||
that brings Cucumber to Rails 5.x and 6.x. | ||
|
||
The rest of this document is a guide for those maintaining Cucumber, and others who would like to submit patches. | ||
In any case, if your are not sure, best places to open an issue are the current | ||
repository - `cucumber-ruby` - and the mono-repo at [cucumber/common]. | ||
|
||
## Talking with other devs | ||
### Look for existing issues and pull requests | ||
|
||
You can chat with the core team on https://gitter.im/cucumber/contributors. We try to have office hours on Fridays. | ||
Search in [the current repository][cucumber-ruby-issues], in the | ||
[mono-repo][cucumber/common-issues], but also in the | ||
[whole cucumber team][cucumber-issues] if the problem or feature has already | ||
been reported. If you find an issue or pull request which is still open, add | ||
comments to it instead of opening a new one. | ||
|
||
## Installing your own gems | ||
### Submitting a pull request | ||
|
||
A `Gemfile.local`-file can be used to have your own gems installed to support your normal development workflow. | ||
Execute `bundle config set --local gemfile Gemfile.local` to use it per default. | ||
When submitting a pull request: | ||
|
||
Example: | ||
- create a draft pull request | ||
- try to follow the instructions in the [template](.github/PULL_REQUEST_TEMPLATE.md) | ||
- if possible, [sign your commits] | ||
- update CHANGELOG.md with your changes | ||
- once the PR is ready, request for reviews | ||
|
||
More info on [how to contribute to the code](#contribute-to-the-code) can be | ||
found below. | ||
|
||
### Opening a new issue | ||
|
||
To open a good issue, be clear and precise. | ||
|
||
If you report a problem, the reader must be able to reproduce it easily. | ||
Please do your best to create a [minimal, reproducible example][minimal-reproducible-example]. | ||
|
||
Consider submitting a pull request. Even if you think you cannot fix it by | ||
yourself, a pull request with a failing test is always welcome. | ||
|
||
If you request for an enhancement - a new feature, be specific, support your | ||
request with referenced facts and include examples to illustrate your proposal. | ||
|
||
## Contribute to the code | ||
|
||
### Development environment | ||
|
||
Development environment for `cucumber-ruby` is a simple Ruby environment with | ||
Bundler. Use a [supported Ruby version](./README.md#supported-platforms), make | ||
sure [Bundler] is set-up, and voilà! | ||
|
||
You can then fork and clone the repository. If your environment is set-up | ||
properly, the following commands should install the dependencies and execute all | ||
the tests successfully. | ||
|
||
```shell | ||
bundle install | ||
bundle exec rake | ||
``` | ||
|
||
You can now create a branch for your changes and [submit a pull request](#submitting-a-pull-request)! | ||
|
||
If you want to check the code coverage during your development, execute | ||
`bundle exec rake cov`. | ||
|
||
### Cucumber-ruby-core | ||
|
||
As seen here: [Find the appropriate repository](#find-the-appropriate-repository), | ||
you may need to work with other repositories in order to accomplish your | ||
development. Beside the mono-repo in [cucumber/common], [cucumber-ruby-core] is | ||
also a big piece of `cucumber-ruby`. | ||
|
||
### Using a local Gemfile | ||
|
||
A local Gemfile allows you to use your prefer set of gems for your own | ||
development workflow, like gems dedicated to debugging. Such gems are not part | ||
of `cucumber-ruby` standard `Gemfile`. | ||
|
||
`Gemfile.local`, `Gemfile.local.lock` and `.bundle` have been added to | ||
`.gitignore` so local changes cannot be accidentaly commited and pushed to the | ||
repository. | ||
|
||
A `Gemfile.local` may look like this: | ||
|
||
```ruby | ||
# Gemfile.local | ||
|
||
# Include the regular Gemfile | ||
eval File.read('Gemfile') | ||
|
||
# Include your favorites development gems | ||
group :development do | ||
gem 'byebug' | ||
gem 'debase', require: false | ||
gem 'ruby-debug-ide', require: false | ||
gem 'pry' | ||
gem 'pry-byebug' | ||
|
||
gem 'debase', require: false | ||
gem 'ruby-debug-ide', require: false | ||
end | ||
``` | ||
|
||
## Using Visual Studio Code? | ||
Then you can execute bundler with the `--gemfile` flag: | ||
`bundle install --gemfile Gemfile.local`, or with an environment variable: | ||
`BUNDLE_GEMFILE=Gemfile.local bundle [COMMAND]`. | ||
|
||
To use your local Gemfile per default, you can also execute | ||
`bundle config set --local gemfile Gemfile.local`. | ||
|
||
Sample for launch.json configuration is available in | ||
[docs/vscode-example-launch-configuration.md](https://github.com/cucumber/cucumber-ruby/blob/main/docs/vscode-example-launch-configuration.md) | ||
### First timer? Welcome! | ||
|
||
## Note on Patches/Pull Requests | ||
Looking for something simple to begin with? Look at issues with the label | ||
'[good first issue](https://github.com/cucumber/cucumber-ruby/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)'. | ||
|
||
- Fork the project. Make a branch for your change. | ||
- Make your feature addition or bug fix. | ||
- Make sure your patch is well covered by tests. We don't accept changes to Cucumber that aren't tested. | ||
- Please do not change the Rakefile, version, or history. | ||
(if you want to have your own version, that is fine but | ||
bump version in a commit by itself so we can ignore when we merge your change) | ||
- Send us a pull request. | ||
Remember: Cucumber is more than `cucumber-ruby`. You can look for good first | ||
issues in [other cucumber reporistories](#find-the-appropriate-repository). | ||
|
||
## Running tests | ||
### Having trouble getting started with the code? We're here to help! | ||
|
||
gem install bundler | ||
bundle install | ||
bundle exec rake | ||
If you have trouble setting-up your development environment, or getting started | ||
with the code, you can join us on [Slack][community-slack]. You will find there | ||
a lot of contributors. | ||
|
||
To get code coverage results, run `bundle exec rake cov` | ||
Full-time mainteners are also available. We would be please to have 1:1 pairing | ||
sessions to help you getting started. Look for | ||
[Matt Wynne](https://cucumberbdd.slack.com/team/U590XDLF3) or | ||
[Aurélien Reeves](https://cucumberbdd.slack.com/team/U011BB95MC7) on | ||
[Slack][community-slack]. | ||
|
||
## First timer? Welcome! | ||
### Additional documentation and notice | ||
|
||
If you are new to the project or to OSS, check the label | ||
[Easy](https://github.com/cucumber/cucumber-ruby/labels/Easy). Also, you can | ||
help us to correct style violations reported here: | ||
[.rubocop_todo.yml](https://github.com/cucumber/cucumber-ruby/blob/main/.rubocop_todo.yml). | ||
You can find additional documentation in the [docs](./docs) directory such as | ||
(non-exhaustive list): | ||
|
||
## Release Process | ||
- [How to release cucumber-ruby](./docs/RELEASE_PROCESS.md) (for mainteners) | ||
- [How to set-up a launch.json configuration for Visual Studio Code](./docs/vscode-example-launch-configuration.md) | ||
|
||
- Upgrade gems with `scripts/update-gemspec` | ||
- Bump the version number in `lib/cucumber/version` | ||
- Update `CHANGELOG.md` with the upcoming version number and create a new `In Git` section | ||
- Remove empty sections from `CHANGELOG.md` | ||
- Now release it: | ||
|
||
``` | ||
git commit -am "Release X.Y.Z" | ||
make release | ||
``` | ||
<!-- Links --> | ||
|
||
- Finally, update the cucumber-ruby version in the [documentation project](https://cucumber.io/docs/installation/) in [versions.yaml](https://github.com/cucumber/docs/blob/master/data/versions.yaml) file. | ||
[community message board]: https://community.smartbear.com/t5/Cucumber-Open/bd-p/CucumberOS | ||
[register-slack]: https://cucumberbdd-slack-invite.herokuapp.com/ | ||
[slack-intro]: https://cucumberbdd.slack.com/messages/C5WD8SA21/ | ||
[community-slack]: https://cucumberbdd.slack.com/ | ||
[cucumber-docs]: https://cucumber.io/docs/cucumber | ||
[cucumber/common]: https://github.com/cucumber/common | ||
[cucumber-ruby-core]: https://github.com/cucumber/cucumber-ruby-core | ||
[cucumber-ruby-wire]: https://github.com/cucumber/cucumber-ruby-wire | ||
[cucumber-rails]: https://github.com/cucumber/cucumber-rails | ||
[cucumber-ruby-issues]: https://github.com/cucumber/cucumber-ruby/search?q=is%3Aissue | ||
[cucumber/common-issues]: https://github.com/cucumber/common/search?q=is%3Aissue | ||
[cucumber-issues]: https://github.com/search?q=is%3Aissue+user%3Acucumber | ||
[sign your commits]: https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification/signing-commits | ||
[minimal-reproducible-example]: https://stackoverflow.com/help/minimal-reproducible-example | ||
[RVM]: https://rvm.io/ | ||
[rbenv]: https://github.com/rbenv/rbenv | ||
[Bundler]: https://bundler.io/ |
Oops, something went wrong.