Closing a two year old Cucumber Ruby issue

August 5, 2018

Contributing to open source projects as a new developer can be difficult for a number of reasons, including feeling under skilled for the currently open issues or feeling overwhelmed by the size of a project and I’m no stranger to either. If you want to contribute to a project and there doesn’t seem to be anything you feel comfortable with, there are still a number of things you can do to help a project whether it be with code contributions or even outside PRs! I’ll go over those in another post, but here’s my own origin story with the Cucumber community and closing a long lived issue for the Cucucmber-Ruby project.

Beginnings

I don’t remember what my original feelings were around finding issue #1021 with the title of, “Fix style violations” but it was probably quite positive! A ticket around Rubocop?! I knew Rubocop and style changes didn’t require one to have a deep knowledge of the project. This was my ticket in the door, huzzah!

The First PR

non-sharing

The PR that started it all was #172 Fix Lint/DeprecatedClassMethods. Five days from now marks the one year anniversary of my opening it! ๐ŸŽ‰๐ŸŽ‰๐ŸŽ‰

So, what’d I change? For those of you familiar with Github diffs, the diff stat above should indicate just how small my beginnings with the project were. For those who are unfamiliar, it shows how much was changed when comparing two versions of code. In this case, it says that I changed a total of 8 lines, with the majority of the change being deleting content. Comedically, that deleted content was removing the Lint/DeprecatedClassMethods lines from the .rubocop_todo.yml file, followed by the actual style work being a whopping one character change in the project’s project_initializer.rb file! I changed exists? to exist?. While looking back on it gives me a chuckle, it was a hugely important step for me, and, as @mattwynne would say, for the Cucumber-Ruby project itself.

The Wild West

Since Ruby doesn’t have a built in linter/formatter like Go does with gofmt and since it’s pretty lenient with what it accepts, having multiple people contribute to a project with different backgrounds, stylistic preferences, and habits, means the code can end up with quite the variety to it. This type of variance can make things look off, reading the code difficult, and also make it difficult for newcomers to contribute. A common idiom when adding to projects is to follow the existing code’s style. What do you do if when looking around you see different styles across the board? It can make what may be a difficult task and overwhelming one!

Enter Rubocop

From the RuboCop website:

RuboCop is a Ruby static code analyzer. Out of the box it will enforce many of the guidelines outlined in the community Ruby Style Guide.

RuboCop parses your code base and returns back a list of items that it thinks are style violations that need to be improved. It can also output this list as a file I mentioned above, conveniently named .rubocop_toco.yml, allowing you to work through them as you can.

The original version of the todo file from September 6, 2016 had 1,264 lines, indicated that 153 style rules were being violated, and that there were a whopping 7,042 violations! /sweats

You might be thinking, “That’s a lot of work to do!” and it definitely was. Thankfully, some folks had already contributed some fixes and RuboCop provides some assistance in auto-fixing some violations. While it’s been a huge time saver, it doesn’t always do things how we want so there have been some bumps along the way. That’s okay RuboCop, we still love you and you’re still amazing!

I learned a lot about Ruby’s style, shortcuts, and also some about the Cucumber Ruby project itself.

For example:

Instead of

if foo == 'abc' || foo == 'def' || foo == 'ghi'

This is what it’ll suggest:

if %w[abc def ghi].include? foo

Did you know that %w[] is Ruby’s sugary form of a word array? Its equivalent is [‘abc’, ‘def’, ‘ghi’] Check out more here

The above reads much easier, it’s much more concise, and it’s much easier to type out.

Do you know about method-missing? I didn’t before going through these changes and while I still don’t fully grok it, it’s a facet of the Ruby language not everyone may know about.

There are so many things you can learn just by reading through the cop documentation on RuboCop’s site that I highly suggest either going through it or installing RuboCop to your project today!

I had times throughout 1021’s lifespan where I was focused on other things but I persisted and finished. The changes waited patiently for me to finish them. (Even if Stalebot didn’t want me to! ๐Ÿค–) Over the past year, I made a total of 195 commits to the Cucumber-Ruby project with the bulk being toward improving the style of the code.

Finally Closed

As of August 4, 2018 the issue is closed, the repo no longer has a todo file, and the rubocop config file has settings in it that illustrate some special decisions on rules, some leniency on others, and so on. If you’re a new developer or a developer new to the project, having a clear understanding of the conventions for a project and a tool for fixing things can be hugely useful in reducing the barrier for entry to contributing.

If I hadn’t made the initial step above, the project’s style would still need help and I wouldn’t have done the other things I have with the Cucumber community. For instance, in another project of mine around normalizing the CHANGEME files we use, I made changes to nearly every active repo across the whole Cucumber ecosystem!

Thanks for reading!

Jayson

P.S. If you have any questions, comments, etc, please reach out or leave a comment below!