From 44ffcd469cf9abc512e0537fcdfd7820cb8fb387 Mon Sep 17 00:00:00 2001 From: Stefanni Brasil Date: Thu, 13 Apr 2023 18:38:04 -0700 Subject: [PATCH 1/3] 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. --- .github/PULL_REQUEST_TEMPLATE.md | 44 ++++++++++++++++++++++++++------ CONTRIBUTING.md | 32 +++++++++++++---------- 2 files changed, 54 insertions(+), 22 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index c7fdeb8870..4ac9b30529 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,15 +1,43 @@ -### Summary + +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). - -Thanks for contributing to Faker! --> \ No newline at end of file +### Motivation / Background + + + +This Pull Request has been created because [REPLACE ME] + +### Additional information + + + +### 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. +* [ ] This Pull Request is related to adding a new generator. I've reviewed and followed the [Documentation guidelines](https://github.com/faker-ruby/faker/blob/main/CONTRIBUTING.md#documentation). +* [ ] 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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f7d8dc37e7..f844d3c6b6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -71,29 +71,23 @@ 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 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 +167,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. From 9f5f4e94acdaef8c71ce6731423836545a4feb23 Mon Sep 17 00:00:00 2001 From: Stefanni Brasil Date: Fri, 14 Apr 2023 15:00:13 -0700 Subject: [PATCH 2/3] Add suggestions from code review --- .github/PULL_REQUEST_TEMPLATE.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 4ac9b30529..918fac584c 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -38,6 +38,12 @@ This Pull Request has been created because [REPLACE ME] 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. -* [ ] This Pull Request is related to adding a new generator. I've reviewed and followed the [Documentation guidelines](https://github.com/faker-ruby/faker/blob/main/CONTRIBUTING.md#documentation). * [ ] 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). From e5af68cd031be50b948e05c8d2b0ea686db29ee1 Mon Sep 17 00:00:00 2001 From: Stefanni Brasil Date: Fri, 14 Apr 2023 15:15:54 -0700 Subject: [PATCH 3/3] Add note about innapropriate language when adding new generators --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f844d3c6b6..f72f40e11b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -78,6 +78,8 @@ There are a few ways to run RuboCop: ## 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 the `lib/locales/en.yml` file. For example, if you add `Faker::MyThing`, put your translations in `lib/locales/en/my_thing.yml`.