Update Pull Request template and guides (#2749)

* Update Pull Request template and guides

It's easy to forget more details, review the docs when
opening a PR. To help everyone, I'm updating the PR template
and its reference to the documentation guidelines.

* Add suggestions from code review

* Add note about innapropriate language when adding new generators

Author: Stefanni Brasil

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,15 +1,49 @@
-### Summary
+<!--
+Thanks for contributing to faker-ruby!
 
-<!-- Provide a general description of the code changes in your pull request.
+Please do not make *Draft* pull requests, as they still send
+notifications to everyone watching the faker-ruby repo.
 
-Were there any bugs you had fixed? If so, mention them: Fixes Issue #add-issue-number -->
+Create a pull request when it is ready for review and feedback
+from the faker-ruby team :).
 
-### Other Information
+If your pull request affects documentation or any non-code
+changes, guidelines for those changes are [available
+here](https://github.com/faker-ruby/faker/blob/main/CONTRIBUTING.md#documentation).
 
-<!-- If there's anything else that's important and relevant to your pull request, mention that information here.
+About this template
 
-If you are creating a new generator, share how you are going to use it. Use cases are important to make sure that our faker generators are useful. Also, add `@faker.version next` to help users know when a generator was added. See [this example](https://github.com/faker-ruby/faker/blob/aa31845ed54c25eb2638d716bfddf59771b502aa/lib/faker/music/opera.rb#L68).
+The following template aims to help contributors write a good description for their pull requests.
+We'd like you to provide a description of the changes in your pull request (i.e. bugs fixed or features added), motivation behind the changes, and complete the checklist below before opening a pull request.
 
-Finally, if your pull request affects documentation, please follow the [Guidelines](https://github.com/faker-ruby/faker/blob/main/CONTRIBUTING.md#documentation).
+Feel free to discard it if you need to (e.g. when you just fix a typo). -->
 
-Thanks for contributing to Faker! -->
+### Motivation / Background
+
+<!--
+Describe why this Pull Request needs to be merged. What bug have you fixed? What feature have you added? Why is it important?
+If you are fixing a specific issue, include "Fixes #ISSUE" (replace with the issue number, remove the quotes) and the issue will be linked to this PR.
+
+If you're proposing a new generator, please follow the [Documentation guidelines](https://github.com/faker-ruby/faker/blob/main/CONTRIBUTING.md#documentation).
+-->
+
+This Pull Request has been created because [REPLACE ME]
+
+### Additional information
+
+<!-- Provide additional information such as benchmarks, reference to other repositories or alternative solutions. -->
+
+### Checklist
+
+Before submitting the PR make sure the following are checked:
+
+* [ ] This Pull Request is related to one change. Changes that are unrelated should be opened in separate PRs.
+* [ ] Commit message has a detailed description of what changed and why. If this PR fixes a related issue include it in the commit message. Ex: `[Fix #issue-number]`
+* [ ] Tests are added or updated if you fix a bug, refactor something, or add a feature.
+* [ ] Tests and Rubocop are passing before submitting your proposed changes.
+
+If you're proposing a new generator:
+
+* [ ] Open an issue first for discussion before you write any code.
+* [ ] Double-check the existing generators documentation to make sure the new generator you want to add doesn't already exist.
+* [ ] You've reviewed and followed the [Documentation guidelines](https://github.com/faker-ruby/faker/blob/main/CONTRIBUTING.md#documentation).

CONTRIBUTING.md

@@ -71,29 +71,25 @@ There are a few ways to run RuboCop:
 
 ## Managing your branch
 
-- Use well-crafted commit messages and Pull Requests descriptions, providing context if possible.
-
+- Use well-crafted commit messages and Pull Requests descriptions, providing context if possible. Please use the Pull Request template when opening a new PR.
 - Squash "WIP" commits and remove merge commits by rebasing your branch against main. We try to keep our commit history as clean as possible.
 - To prevent pushing with test failures or Rubocop offenses, see [Setup a custom pre-push git hook](#setup-a-custom-pre-push-git-hook).
 
-## A word on the changelog
-
-You may also notice that we have a changelog in the form of CHANGELOG.md. You may be tempted to include changes to this in your branch, but don't worry about this — we'll take care of it!
-
-## Continuous integration
-
-GitHub Actions will kick in after you push up a branch or open a PR. It takes a few minutes to run a complete build, which you are free to monitor as it progresses. First-time contributors may need to wait until a maintainer approves the build.
-
-What happens if the build fails in some way? Don't fear! Click on a failed job and scroll through its output to determine the cause of the failure. You'll want to make changes to your branch and push them up until the entire build is green. It may take a bit of time, but overall it is worth it and it helps us immensely!
-
 ## Adding new generators
 
+### General Guidelines
+
+- Don't include hurtful language that can convey exclusionary behavior, such as racism, sexism, homophobia. Be considerate and mindful of others.
 - Don't use `Array#sample`, `Array#shuffle` and `Kernel#rand` on your new generator if you want to randomly pick values. Instead, you should use the methods provided by the Base class: `sample`, `shuffle` and `rand`. The reason is that we want to preserve the deterministic feature of this gem.
 - Please make sure the generator doesn't exist already before opening a PR.
-- Add a new YAML file to `lib/locales/en` rather than adding translations to `lib/locales/en.yml`. For example, if you add `Faker::MyThing`, put your translations in `lib/locales/en/my_thing.yml`. See [the locale README](./lib/locales/en/README.md) for more info.
+- Add a new YAML file to `lib/locales/en` rather than adding translations to the `lib/locales/en.yml` file. For example, if you add `Faker::MyThing`, put your translations in `lib/locales/en/my_thing.yml`.
+  - When possible, consider adding the new YAML file inside a folder to keep things organized, for example: `lib/locales/en/quotes/parks_and_rec.yml`. See [the locale README](./lib/locales/en/README.md) for more info.
 
-### YARD docs
+### Documentation
 
+Add the new generator to the [Generators list in the README](./README.md#generators) so other people can find them.
+
+#### YARD docs
 - Include [YARD] style docs for all methods that includes:
 - A short description of what the method generates
 - Descriptions for all params (`@param`)
@@ -173,6 +169,16 @@ When in doubt, run `bundle exec rake reformat_yaml['lib/path/to/file.yml']` to r
 * Use the `rake console` task to start a session with Faker loaded.
 * Use `bundle exec yard server -r` to launch the YARD Doc server.
 
+## A word on the changelog
+
+You may also notice that we have a changelog in the form of CHANGELOG.md. You may be tempted to include changes to this in your branch, but don't worry about this — we'll take care of it!
+
+## Continuous integration
+
+GitHub Actions will kick in after you push up a branch or open a PR. It takes a few minutes to run a complete build, which you are free to monitor as it progresses. First-time contributors may need to wait until a maintainer approves the build.
+
+What happens if the build fails in some way? Don't fear! Click on a failed job and scroll through its output to determine the cause of the failure. You'll want to make changes to your branch and push them up until the entire build is green. It may take a bit of time, but overall it is worth it and it helps us immensely!
+
 ## Setup a custom pre-push git hook
 
 There is a custom git hooks pre-push file. Before the push occurs, it runs the tests and Rubocop. If there are any tests failures, or Rubocop offenses, the push is aborted.