Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add document about Create a new cop #123

Merged
merged 2 commits into from
May 24, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions docs/modules/ROOT/pages/development.adoc
Original file line number Diff line number Diff line change
@@ -1,3 +1,44 @@
= Development

This page describes considerations when developing Capybara-specific cops. It is intended to be a complement to the general https://docs.rubocop.org/rubocop/development.html[RuboCop development documentation].

== Create a new cop

NOTE: Clone the repository and run `bundle install` if not done yet.
The following rake task can only be run inside the rubocop project directory itself.

Use the bundled rake task `new_cop` to generate a cop template:

[source,sh]
----
$ bundle exec rake 'new_cop[Capybara/CopName]'
[create] lib/rubocop/cop/capybara/cop_name.rb
[create] spec/rubocop/cop/capybara/cop_name_spec.rb
[modify] lib/rubocop/cop/capybara_cops.rb - `require_relative 'capybara/cop_name'` was injected.
[modify] A configuration for the cop is added into config/default.yml.
Do 4 steps:
1. Modify the description of Capybara/CopName in config/default.yml
2. Implement your new cop in the generated file!
3. Add an entry about new cop to CHANGELOG.md
4. Commit your new cop with a message such as
e.g. "Add new `#{badge}` cop"
----

=== Choose a Name

Use the following rules to give the new cop a name:

* Pick a department. See the xref:cops.adoc[list of existing departments]
* The name is self-explanatory
* The name explains the offense the cop detects, e.g. `ExtraSpacing`
* The name starts with a noun instead of a verb, e.g. `ArrayAlignment` instead of `AlignArray`
* The name is easy to understand, e.g. `IndentationStyle` instead of just `Tab`
* The name is specific, e.g. `DuplicateHashKey` instead of just `DuplicateKey`
* The name is neutral when possible and accommodates multiple styles when feasible, e.g. `EmptyLineBeforeBegin`.
* The name uses commonly-used terms, e.g. `RedundantPercentI` instead of `RedundantPercentSymbolArray`
* The name uses correct terms, e.g. arguments in a method call, and parameters in a method signature
* Lines with no symbols are called "empty", not "blank", e.g. `LeadingEmptyLines` instead of `LeadingBlankLines`
* Prefer "redundant" to "unneeded", e.g. `RedundantSelf` instead of `UnneededSelf`

See the https://github.com/rubocop/rubocop/blob/12fd014e255617a08b7b42aa5df0745e7382af88/config/obsoletion.yml#L4["renamed" section of `config/obsoletion.yml`]
for good and bad examples (old name is on the left, new name on the right).