Skip to content

Latest commit

 

History

History
249 lines (176 loc) · 11.3 KB

CONTRIBUTING.md

File metadata and controls

249 lines (176 loc) · 11.3 KB
Raw

Contributing to Faker

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.

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.

Reporting a bug

Have a fix for a problem you've been running into? Here's what you need to do:

What contributions we are looking for

faker-ruby already has lots of generators and locales. We appreciate any efforts made into updating the existing locales by:

  • adding new translations
  • updating the existing translations
  • fixing any outdated/wrong translations

Note

Please include the console output of the translations in the PR description. Run bundle exec rake console to confirm the translations are working as expected. Here's an example.

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!

Setting up your environment

Faker requires Ruby version >= 2.7. After forking, and cloning the repo, navigate to the directory, and run:

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:

bundle exec rake test

Code Style

We use 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:

`bundle exec rubocop` #-> to run Rubocop only
`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. Please use the Pull Request template when opening a new PR.
  • When updating documentation, or README, skip running CI.
  • 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.

Adding new generators/locales

The faker-ruby team has decided to stop accepting any new features, including generators and locales. Please see What contributions we are looking for for other ways you can help.

This allows us to focus on improving the performance and organization of the library. We appreciate your understanding and we are looking forward to get your help with making faker faster and easier to use.

General Guidelines

Once the feature has met the requirements above, please review these guidelines before opening a PR:

  • Avoid:
    • Hurtful language that can convey exclusionary behavior, such as racism, sexism, homophobia.
    • Graphically violent or harmful terms towards any living beings.
    • When possible, avoid the use of figurative language that can be interpreted as violent, such as hang, and hit.
    • Unnecessarily gendered language.
  • Be considerate and mindful of others as much as possible.
  • When adding new generators, limit the number of values per generator in the YML file. Adding a long YML file makes it harder to review your PR.
  • 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.
  • Make sure the generator doesn't exist already before opening a PR.
  • Use the PositionalGenerator helper when generating a list of generated values that fit a specific format, such as an ID, postal code, or phone number.
  • 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 for more info.

Documentation

Add the new generator to the Generators list in the README 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)
  • 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

Here is an example:

##
# Produces a random string of alphabetic characters, (no digits)
#
# @param char_count [Integer] The length of the string to generate
#
# @return [String]
#
# @example
#   Faker::Alphanumeric.alpha #=> "kgdpxlgwjirlqhwhrebvuomdcjjpeqlq"
#   Faker::Alphanumeric.alpha(number: 10) #=> "zlvubkrwga"
#
# @faker.version next
def alpha(number: 32)
    # ...
end

Removing generators

To remove a generator or any other public method, deprecate them first. We use the Gem::Deprecate.

To deprecate a method/argument, add extend Gem::Deprecate to the top of the class, and use the deprecate method. For example:

module Faker
  class LoremPixel < Base
    class << self
      extend Gem::Deprecate
      def image
      ...
      end
      deprecate :image, 'Faker::LoremFlickr.image', 2022, 12
    end
  end
end

Deprecating Generators

To deprecate entire generators and provide backwards compatibility when it's possible, use this custom Faker::Deprecator helper module. It's useful for renaming a generator, for example, renaming IDNumber to IdNumber. Here's how to use it:

  • include the Faker::Deprecator module after the class definition.
  • add the deprecate_generator method with the old and new class names as arguments.
module Faker
  class IdNumber < Base
    ## methods
  end

  include Faker::Deprecator
  deprecate_generator('IDNumber', IdNumber)
end

Faker::IDNumber is now deprecated. Despite the deprecation, it will still be available with logged warnings and will be removed in the next major release.

Faker::IDNumber.valid #=> "552-56-3593"

## Deprecation warning
DEPRECATION WARNING: Faker::IDNumber is deprecated. Use Faker::IdNumber instead.

We recommend adding tests for both the deprecated and new generators to ensure that the deprecation process is working as expected. Check out this PR for reference.

YAML files

Please use dash syntax for YAML arrays. The dash syntax facilitates code reviews by making it easier to see what items were added or removed from the lists.

Here is an example:

# 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,
]

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.

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.

To set up:

  • Copy the file pre-push.sample located in the custom-hooks folder.
  • Paste it in your .git/hooks folder without the .sample extension.
  • Run chmod +x .git/hooks/pre-push to make the file executable (not needed for Windows users).

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.