Update README and CONTRIBUTING guides

CONTRIBUTING.md

@@ -1,57 +1,108 @@
-We love pull requests. Here's a quick guide:
+# Contributing to Faker
 
-1. Fork the repo.
+We are always happy to make improvements to Faker. There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, submitting bug reports and feature requests or writing code which can be incorporated into Faker itself.
 
-2. Run the tests. We only take pull requests with passing tests, and it's great to know that you have a clean slate: `bundle && bundle exec rake`
+Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, they should reciprocate that respect by addressing your issue, assessing changes, and helping you finalize your pull requests.
 
-3. We are using [RuboCop](https://github.com/bbatsov/rubocop) because we love static code analyzers.
-    * Ways to run RuboCop:
-        - `bundle exec rubocop`
-        - `bundle exec rake` would run the test suite and after that it runs the Ruby static code analyzer.
-        - To prevent pushing with test failures or rubocop offenses, see [Setup a custom pre-push git hook](#setup-a-custom-pre-push-git-hook)
 
-4. Please add a test for your change. Only refactoring and documentation changes require no new tests. If you are adding functionality or fixing a bug, we need a test! We use [Minitest](https://github.com/seattlerb/minitest) in this project.
+Have a fix for a problem you've been running into or an idea for a new feature you think would be useful? Here's what you need to do:
 
-5. Make the test pass. Always use `sample`, `shuffle`, and `rand` from the Base class (just like the rest of the code) rather than `Array#sample`, `Array#shuffle` and `Kernel#rand` to preserve the deterministic feature.
+- Fork this repo and clone your fork to somewhere on your machine.
+- [Ensure that you have a working environment](#setting-up-your-environment).
+- Read up on the [architecture of the gem](#architecture), [how to run tests](#running-the-tests), and [the code style we use in this project](#code-style).
+- Cut a new branch and write a failing test for the feature or bugfix you plan on implementing.
+- [Make sure your branch is well managed as you go along](#managing-your-branch).
+- Review the guidelines for [adding new generators](#adding-new-generators), [adding YAML files](#yaml-files), and [YARD docs](#yard-docs).
+- [Refrain from updating the changelog](#a-word-on-the-changelog).
+- Push to your fork and submit a pull request.
+- [Ensure that the test suite passes on GitHub Actions and make any necessary changes to your branch to bring it to green](#continuous-integration).
 
-6. We care about code coverage and use `SimpleCov` to analyze the code and generate test coverage reports. It's possible to check the test coverage by running  `open coverage/index.html`. Please make sure to not decrease our `current % covered` and add appropriate test cases when necessary.
+Although we maintain Faker in our free time, we try to respond to contributions in a timely manner. Once we look at your pull request, we may give you feedback. For instance, we may suggest some changes to make to your code to fit within the project style or discuss alternate ways of addressing the issue in question. Assuming we're happy with everything, we'll then bring your changes into main. Now you're a contributor!
 
-7. When adding a new class, 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.
+## Setting up your environment
 
-8. When removing a method, don't forget to deprecate it. You can `extend Gem::Deprecate` and use the `deprecate` method to accomplish this task.
+Faker requires Ruby version >= 2.7. After forking, and cloning the repo, navigate to the directory, and run:
 
-9. Methods with optional arguments should use keyword rather than positional arguments. An exception to this could be a method that takes only one optional argument, and it's unlikely that that method would ever take more than one optional argument.
 
-10. Push to your fork and submit a pull request.
+```ruby
+bundle install
+```
+
+Run `rake` to ensure the project is all setup. It runs the tests and rubocop. That means you're good to go!
+
+## Architecture
+
+This project follows the typical structure for a gem: code is located in `/lib` and tests are in `/test`. Generators
+
+docs are available in the `/doc` folder.
+
+
+## Running the tests
+
+To run all of the tests, simply run:
+
+```ruby
+bundle exec rake test
+
+```
+
+## Code Style
+
+We use [RuboCop](https://github.com/bbatsov/rubocop) as our static code analyzer.
+
+Please follow these guidelines when adding new code:
+* Use keywords arguments.
+* Two spaces, no tabs.
+* No trailing whitespace. Blank lines should not have any space.
+* Prefer `&&`, `||` over `and`, `or`.
+* `MyClass.my_method(my_argument: my_arg)` not `my_method( my_arg )` or `my_method my_arg`.
+* `a = b` and not `a=b`.
+* In general, follow the conventions you see being used in the source already.
+* Rubocop errors must be resolved for the PR to be approved.
+  * To fix all the offenses automatically with Rubocop's autocorrection tool, run `bundle exec rubocop -A`
+
+There are a few ways to run RuboCop:
+
+```ruby
+`bundle exec rubocop` #-> to only run Rubocop
+
+`bundle exec rake` #-> to run the test suite and rubocop after.
+```
+
+## Managing your branch
+
+- Use well-crafted commit messages and Pull Requests descriptions, providing context if possible.
+
+- 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
 
-### Github Flow for contributors and collaborators
+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!
 
-For those of you with commit access, please check out Scott Chacon's blog post about [github flow](http://scottchacon.com/2011/08/31/github-flow.html)
+## Continuous integration
 
-> * Anything in the main branch is deployable
-> * To work on something new, create a descriptively named branch off of main (ie: new-oauth2-scopes)
-> * Commit to that branch locally and regularly push your work to the same named branch on the server
-> * When you need feedback or help, or you think the branch is ready for merging, open a pull request
-> * After someone else has reviewed and signed off on the feature, you can merge it into main
+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.
 
-If you're reviewing a PR, you should ask yourself:
-> * Does it work as described? A PR should have a great description.
-> * Is it understandable?
-> * Is it well implemented?
-> * Is it well tested?
-> * Is it well documented?
-> * Is it following the structure of the project?
+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!
 
-### Syntax/Good practices:
+## Adding new generators
 
-#### Documentation
-Include [YARD] style docs for all methods that includes:
+- 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.
+
+### YARD docs
+
+- Include [YARD] style docs for all methods that includes:
 - A short description of what the method generates
 - Descriptions for all params (`@param`)
 - The return type (`@return`)
 - At least one example of the output (`@example`)
 - The version that the method was added (`@faker.version`)
-  - Set as `next` for new methods or methods with new features 
+  - Set as `next` for new methods or methods with new features
+
+Here is an example:
 
 ```ruby
 ##
@@ -71,45 +122,47 @@ def alpha(number: 32)
 end
 ```
 
-#### Code Styles
-Please follow these guidelines when adding new code:
-* Two spaces, no tabs.
-* No trailing whitespace. Blank lines should not have any space.
-* Prefer `&&`, `||` over `and`, `or`.
-* `MyClass.my_method(my_arg)` not `my_method( my_arg )` or `my_method my_arg`.
-* `a = b` and not `a=b`.
-* In general, follow the conventions you see used in the source already.
-* **ALL SHALL OBEY THE RUBOCOP**
+[YARD]: (https://www.rubydoc.info/gems/yard/file/README.md)
+
+## Removing generators
+
+To remove a generator or any other public method, deprecate them first. We use the `Gem::Deprecate`[https://ruby-doc.org/stdlib-3.1.0/libdoc/rubygems/rdoc/Gem/Deprecate.html].
+
+To deprecate a method/argument, add `extend Gem::Deprecate` to the top of the class, and use the `deprecate` method.
+
+## YAML files
+
+Please use dash syntax for YAML arrays. The dash syntax faciliates code reviews by making it eaiser to see what items were added or removed from the lists.
+
+Here is an example:
 
-#### YAML
-Please use dash syntax for yaml arrays:
 ```Yaml
+# this is preferred
+a_things:
+  - small_thing
+  - big_thing
+  - other_thing
+
 # instead of these
 b_things: [small_thing, big_thing, other_thing]
 c_things: [
   small_thing,
   big_thing,
   other_thing,
 ]
-
-# this is preferred
-a_things:
-  - small_thing
-  - big_thing
-  - other_thing
 ```
-- If in doubt, `bundle exec rake reformat_yaml['lib/path/to/file.yml']`
 
-### Tips
+When in doubt, run `bundle exec rake reformat_yaml['lib/path/to/file.yml']` to reformat your YAML file.
+
+## Tips
 
 * Use the `rake console` task to start a session with Faker loaded.
-* Use `bundle exec yard server -r` to launch the YARD Doc server
+* Use `bundle exec yard server -r` to launch the YARD Doc server.
 
-[YARD]: (https://www.rubydoc.info/gems/yard/file/README.md)
+## Setup a custom pre-push git hook
 
-### 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.
 
-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.
 
 To set up:
 - Copy the file `pre-push.sample` located in the `custom-hooks` folder.
@@ -120,4 +173,4 @@ To skip this hook for any push, add `--no-verify` to the end of the command:
 
 `git push --no-verify <remote_name> <branch_name>`
 
-To disable this hook completely: remove the file `.git/hooks/pre-push`
+To disable this hook completely: remove the file `.git/hooks/pre-push`.

MAINTAINING.md

@@ -0,0 +1,21 @@
+### Maintaining Faker
+
+As maintainers of the gem, this is our guide. Most of the steps and guidelines in the Contributing document apply here, including how to set up your environment, write code to fit the code style, run tests, craft commits and manage branches. Beyond this, this document provides some details that would be too low-level for contributors.
+
+If you're reviewing a PR, you should ask yourself:
+> * Does it work as described? A PR should have a great description.
+> * Is it understandable?
+> * Is it well implemented?
+> * Is it well tested?
+> * Is it well documented?
+> * Is it following the structure of the project?
+
+# TODO
+
+- Communication
+- Workflow
+- Versioning
+- Issuing new releases
+- Updating the Changelog
+- Granting Rubygems access
+- Labels