Contributing

Wow, you want to contribute? That's awesome! Thanks!

To make things easier on you, here are some notes and guidelines. The rest of the wiki may also be useful.

Recommendations

Use Docker or Vagrant

This is paramount as the test suite will write files to your homedir and potentially elsewhere.

Historically, the tests used FakeFS which didn't touch the live filesystem.

FakeFS use is being gradually removed, but legacy tests use ~ to write test files and don't delete them afterwards. This wasn't a concern with FakeFS as we'd get a clean filesystem every time. Replacing uses of ~ by /tmp/maid-test/ is tracked in https://github.com/maid/maid/issues/316.

Docker

Ruby 3:

$ rake guard:docker   # will run `guard` in a container

Ruby 2.7 (useful for fixing specs that only fail for ruby-2.7):

$ rake guard:docker27  # same thing but with ruby-2.7

Vagrant

$ vagrant up && vagrant ssh --command 'cd /vagrant && bundle exec guard'

The Vagrant box can take a little while to provision, because some ruby versions must be compiled from source (see https://github.com/maid/maid/issues/314.)

Running rspec anyway outside an isolated environment

Be advised, this will write to your live filesystem and to your homedir.

If you wish to do it anyway (seriously, don't!), set the ISOLATED=true env var and then run rspec.

Targeted Ruby versions

See SECURITY.md for current support status.

Ruby version for development

See .ruby-version for which version to use while developing.

If you're using RVM, rvm use will switch to the correct Ruby version (or prompt you to install it) and use the maid-dev gemset.

Guard

We recommend using Guard for development. It will run all the specs and correct minor styles issues automatically every time a .rb file is written.

Run it with bundle exec guard, manually run Rubocop by typing rubocop at the prompt, manually run specs by typing rspec at the prompt.

Style

Maid uses Rubocop to enforce style. The rules are defined in two places: .rubocop.yml and .rubocop_todo.yml. The latter file containing overrides to the rules in .rubocop.yml. The objective is to delete .rubocop_todo.yml evenutally as the overrides become unnecessary.

For all intents and purposes, the rules in .rubocop.yml are to be followed.

Running bundle exec guard will automatically correct minor style issues every time a .rb file is saved.

The GitHub Actions pipeline includes a linting job, and will fail the build if Rubocop reports any issue.

Testing

Run existing tests with bundle exec rspec or through Guard (bundle exec guard, then rspec at the prompt).

Code coverage data is output for each test run at coverage/index.html. The build will fail if test coverage drops, so please make sure to add tests for your changes.

To maintain code quality and help future refactoring efforts, we cannot merge patches that don't come with tests.

Documentation

Use Markdown, as understood by YARD. Run yard to generate.

See https://www.rubydoc.info/gems/yard/file/docs/Tags.md for documentation on the YARD format.

Patches/Pull Requests

• Fork the project.
• Make your changes. Please follow the style recommendations (see above).
• Ensure you've added specs that cover your changes. This is important to maintain quality standards and help refactoring in the future.
• Open a PR.