Building a Well-Polished Ruby Gem

A gem is a package for Ruby to distribute code in a maintained unit. But that's not all there is to it. A Ruby gem can also contain full documentation and testing. And gems can be further configured for external services for quality, test suite, and documentation verification.

When you're publishing code for other people to use, you're also presenting something that needs to meet quality standards before many will consider using your code. What you publish as a gem will also reflect on you. If you write code without testing, people will find your code less trustworthy. If you don't write documentation, then the intent of your code may not come across clearly.

When publishing a gem, you should strive for a level of excellence above what you would expect from others. The more quality you provide with all of your published gems, the more likely people will trust you and your code. Here are some considerations to think about when building your Ruby gem.

The only file needed to prepare a gem to publish is a gemspec file. In this file, you detail what files are included, author details, description, test and executable details, and dependencies. This information is what will be seen when your gem is looked up on rubygems.org.

If you host the source code on GitHub, you should put that link in your gemspec as the homepage, providing you don't have a site for it already. This makes the README.md file in your gem project the most important first impression you will leave on people who check out your gem. This is the place potential users will look to first for information about what the gem is and how to use it. To make your README visually appealing, become familiar with Markdown and include some graphics and badges if you can (which we'll cover soon). This will help greatly with presentation.

Now, even though you just need a gemspec to build and publish your gem, it will be far more convenient to use Bundler to generate a project template bundle gem thing. It creates a Rakefile for completing your common gem tasks quickly and conveniently. In this template directory, your can run rake -T to see what tasks are available to you.

Within the Ruby community, some argue that you don't need to write documentation on your code; you just need to write your code in a way that it can be understood when read.

While it's a very good practice to make your code understandable, it's not always realistic to assume the code will be understood as read. For example, it's possible that some code will change, and the context will lose meaning. Also, consider that people come to Ruby from different backgrounds. Someone who used to write Perl is far more likely to write cryptic code than someone who comes from Python. And not everyone will have as much knowledge about Ruby as you do.

Documenting your code invites people from all backgrounds to use and possibly contribute to your work.

Beyond the README file, Ruby has long supported a format of documentation called rDoc, which produces HTML and online documentation for Ruby projects. There are websites that will generate documentation publicly directly from rubygems.org.

You may learn rDoc to document your code if you wish, but I would like to inform you about Yard. Yard is an rDoc compatible alternative that lets you write smaller and more concise documentation on your code and still generate full rDoc documentation.

Testing shows you care. It shows dedication toward proving the quality of code and provides a reasonable assumption of stability in the future should changes or new additions occur in the project.

It's not so important what test suite you use as long as you write tests. I have worked in situations where I wrote Minitest tests in the test folder and others wrote rSpec tests in the spec folder, and the Rakefile had tasks for both.

Now separate test suites is not advisable, but if that's what it takes to get everyone on board, then it's a good compromise.

Testing itself is a form of documentation. Tests provide more context to the code you've written because they provide "real world examples."

When code and documentation fail to provide understanding as to the intent of the code, that is where the test suite comes in. People look at tests to see what's expected for input and output and can infer in what situations that code would be best applied. For this reason, try to follow good disciplines for organized, clear coding practices in your tests (since tests often have a tendency of becoming complex).

GitHub has permitted Shield Badges in their markdown, which looks like a bright sign showing important details. These are commonly used with third-party services that verify quality and validity of code and documentation, but they may be used for other purposes as well.

Each service will provide a markdown-compatible badge link, which you will need to place at the top of your README.md file in your project. This badge will update each time the third-party service evaluates your repository.

Code Climate provides a nice free service for open-source projects. They provide two badges that you can add to your project: one for code quality (which evaluates complexity), and one for code coverage (which verifies that every line of code is covered by the test suite).

The code quality ranks your code up to a 4.0 GPA and will have individual ratings per file that you can review on their site. You can view details by clicking on the badge in the README. This is a helpful tool for you to improve your own code, but it's also a testament to others as to what they'll be working with.

Having a badge showing that the code is well-documented enables consumer confidence in your gem.

Your gem's README really is the homefront for the world to be introduced to your gem. As such, a little bit of polish will go a long way here.

If nothing else, add the gem version badge provided from rubygems.org. If your gem headlines in a newsletter, you can create a custom badge from shields.io, proclaiming your gem was "Featured in: Ruby X Newsletter #149." When others have deemed a project worthy of mention, that act of recognition is a helpful piece to note in your README.

You can place images anywhere within the README. I recommend creating an assets folder to store those images in within the same repo. Be sure to remove the directory from inclusion in your gemspec so the image files won't be given to everyone who installs the gem. When including the image link just navigate to the folder on GitHub where the image is and copy the link directly to your README with the image markdown `

`.

A code of conduct can be a controversial thing within programming communities. Look at any major programming language, and it's likely there have been exhaustive discussions on the matter. For example, Ruby went through a long discussion not that long ago on the Ruby issue tracker #12004.

By default, Bundler includes a generic code of conduct file in the project template. You can chose to remove it if you wish, or even disable Bundler from including it in its config file ~/.bundle/config by adding BUNDLE_GEM__COC: 'false' to it.

There should be no reason for your gem to become a front in an unrelated controversy. Make sure that issue threads and content stay related to the project. If someone has a nontechnical issue with someone else, keep it outside the project.

Be considerate of possible misunderstandings created from ignorance and language barriers. Also keep in mind that open source covers the globe, and societies differ in their issues of sensitivity. Should issues arise that may lead to conflict, it's wise to try to win the person rather than the argument.

A gem is a simple thing, and yet it brings the world exposure to a tiny bit of you. While it's true that "you are not your code," and you shouldn't stress over people judging you based on your code, you can still establish trust by presenting clarity, stability, and value. A little bit of effort in your gem could go a long way.

Of course, you don't need to stress over having your gem perfect with all the bells and whistles. However, consider gradually improving bit by bit as you go forward. The first release of a gem will likely have flaws. Strive to make the next one better.

Good luck building your Ruby gems, and I hope that the information provided here is helpful to you.