ParadoxV5/template-ruby-gem

a moderate yet thorough template for a Ruby Gem project

template-ruby-gem

Built upon ParadoxV5/mygem, this is a moderate yet thorough template for a Ruby Gem project. Note: just gem. The rake is for invoking minitest (See §Rakefile.

How to Setup

• Rename all occurrences of mygem, lower- or title-case, with the name of your epic Gem.
  • lib/mygem/
  • lib/mygem.rb and Line 1 & 2
  • lib/mygem/version.rb Line 3
  • sig/mygem.rbs and Line 1
  • test/mygem_test.rb and Lines 3 & 4
  • mygem.gemspec and Lines 2, 5 & 7
• Update the gemspec with your Gem’s information. (See §*.gemspec)
• Overwrite this README with an introduction to your epic project.
• Replace this template’s LICENSE.txt with one that engraves your honor for posterity.
• Add your “Push rubygem” API key as a GitHub Secret (aptly) named GEM_HOST_API_KEY. (See §package.yml))

What’s Inside

Follow the convention regarding the file structure:

lib/**

This is the folder where people put their Gem sources, starting with their entry script right under lib and the rest in a sub-folder.

sig/**

Have you heard of RBS? Yep, Ruby 3 introduced this official type checking system. The convention is to put your RBS signatures in this folder.

*.gemspec

The gemspec is the metadata file for your epic Gem. Any file name is technically acceptable, but a .gemspec suffix is the convention. I have also neatly prepared developer, license and URL information lines in the metadata, though you can remove any bells and whistles that don’t apply to your project.

Gemfile

The Gemfile is the Bundler project file where you would declare dependencies if only using Bundler (i.e., not cutting a Gem). For Gems, the gemspec already covers this role in its metadata – mostly.

There was a discussion before about whether the Gemfile makes .gemspec’s add_development_dependency obsolete: rubygems/rubygems#1104

Overall, I took their conclusion as – Bundler (Gemfile) and RubyGem (.gemspec) are two separate utilities; it’s just good Rubyists like us that use them together.

LICENSE.txt

See §License

Rakefile

The cool li’l testing toolkit minitest does not come with an executable, but rather a Ruby API that generates a handful of Rake tasks.

README.md

You are reading this right now, so you should know what this is for…

.github/workflows/*

Inside this folder are small but thoroughly configured (minimal modification required) GitHub Actions scripts that enable basic continuous deployment:

documentation.yml

Generate YARD docs and publish to GitHub Pages after the main branch receives an update in the Ruby sources (lib/) folder.

test.yml

Run tests independently (rake test:isolated) after any branch receives an update on the .gemspec (in the event of library version changes) or in the sources (lib) or test (test) folders.

type_check.yml

Check your RBS appendices (see §sig/**) after any branch receives an update on the .gemspec (in the event of library version changes) or in the sources (lib) or signature (sig) folders.

package.yml

Publish to RubyGems after the GitHub repo publishes a Release. This workflow requires a “Push rubygem” API key as a GitHub Secret named GEM_HOST_API_KEY in order to authenticate an upload for you.

.github/dependabot.yml

What’s a dependency, you may ask? Well, if your project uses another project to do stuff, your project then depends on that project; got it? Dependabot can do the update check part of the housekeeping so you can focus on your own responsibility.

.yardopts

The .yardopts file records the default command-line parameters, so both you and automated doc bots only need to execute yard doc.

• --markup markdown – Who doesn’t use Markdown?
• --markup-provider commonmarker – Use the CommonMarker Gem instead of whatever impaired default it happens to be out-of-the-box (mine was RDoc::Markdown).

.gitignore

The .gitignore file lists file patterns to exclude from Git’s records.

• Omitting Gemfile.lock and rbs_collection.lock.yaml encourages the use (or experimentation) of updated (yet (hopefully) compatible) dependency versions. Check them in if your paranoia prefers the guarantee of identical functioning dependency versions.
• Don’t include IDE (just JetBrains ones like RubyMine at the movement) configurations unless you want to enforce your organization’s digital environment.

License

I have determined that this template is all traditional knowledge and no copyrightable production. Therefore, I am licensing this template under the infamous WTFPL.