-
Notifications
You must be signed in to change notification settings - Fork 3.2k
/
Copy pathCONTRIBUTING.md
204 lines (144 loc) · 9.24 KB
/
CONTRIBUTING.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
# 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.
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:
- 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).
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:
```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 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 worfklow runs](https://docs.github.com/en/actions/managing-workflow-runs/skipping-workflow-runs).
- 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).
## Adding new generators
### General Guidelines
- 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](https://github.com/faker-ruby/faker/blob/main/lib/helpers/positional_generator.rb) 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](./lib/locales/en/README.md) for more info.
### 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`)
- 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:
```ruby
##
# 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
```
[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. For example:
```rb
module Faker
class LoremPixel < Base
class << self
extend Gem::Deprecate
def image
...
end
deprecate :image, 'Faker::LoremFlickr.image', 2022, 12
end
end
end
```
## 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:
```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,
]
```
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`.