Improvement of welcoming documentation

.github/PULL_REQUEST_TEMPLATE.md

@@ -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

CONTRIBUTING.md

@@ -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/