ruby-scaffold_gem/ReadMe.org

Ruby - Scaffold Gem

A gem scaffolding script with basic security in mind.

Version: 0.4.0

Scaffold currently tested, and used, successfully on macOS. According to/ /CI there is a bug in the script. Unfortunately, we couldn't reproduce it.

Why?

Although there are a few options for scaffolding gems, each focuses on different aspects of gem production but security.

Requirements

This script, as well as the resulting gem scaffold, require one of the latest two Ruby releases; 2.5.X, or 2.6.X.

Quick Start

Download

To use this scaffold

$ git clone https://notabug.org/rem/ruby-scaffold_gem.git <gem_dir>

If you prefer not to open an account on NotABug.org

$ git clone git@notabug.org:rem/ruby-scaffold_gem.git <gem_dir>

You can even get it via tor

Usage

The scaffold is meant to be run from the command line. It requires some basic info:

• namespace.
• author.
• email
• repo.
• license.

$ cd <gem_dir>
$ ruby scaffold_gem.rb -n SomeGem -b -a me -e me@email.com -r https://example.com -l ISC

The supported namespace format is camel cased (SomeGem). It supports a scoped namespace for plugins according to RubyGems conventions (SomeGem::SomePlugin). Since the convention is only at the namespace level, and not on the type of container (class or module), this scaffold generates class SomeGem containing module SomePlugin.

As for the other options, author refers to the person starting the gem. ~email~ to the maintainers' emails. repo points to where the gem's code is hosted. license the type of license to use for the gem. Rubygems expects a license short identifier based on the SPDX license list.

The scaffold includes a copy of ISC license for convenience only. You can use whichever license you want on your gem.

To list all options run

$ ruby scaffold_gem.rb --help

Review

Once the scaffold is generated change ~/lib//doc.rb~'s summary and description. The current ones are set simply to pass the tests.

Chances are that running the tests for the first time, will raise warnings due to mismatched indentation, but no actual failures. Indentation issues won't get fix, that's the code editor's job.

Make sure to skim all the files. This is merely a scaffold, and some useful stuff might had to be commented-out to pass all tests.

Contents at a glance

A Manifest.md with all the files included in the gem package. Meant to be edited by hand. A test case fails when the Manifest.md contents don't match those of the lib, and bin directories.

Although it doesn't assume a particular git web service; it does take advantage of gitlab's continuous integration. The test suite is run under Linux using Ruby's de facto distro, and Alpine.

It includes a few development tasks from code metrics to building the documentation. The list of development dependencies included can be found at the bottom of the _gem_name.gemspec.erb file.

The scaffold itself includes tests checking the completeness of the documentation. Although an incomplete documentation won't fail the CI run by default it publishes the documentation using Gitlab pages.

Gem releases are not automated on the CI script to prevent leaking credentials to the pipeline logs.

The gemspec~'s details, other than the dependencies, have been extracted to help prevent unplanned changes. The relevant files are in ~lib/<gem_name>/ as doc.rb, manifest.rb, and version.rb.

On the generated scaffold, we can run the test suite in full using ~bundle exec rake~. For development, though, use ~./dev/autotest~ to keep the tests on running. Use C-c (SIGINT) twice to stop autotest.

License

Copyright (c) 2018-2019, René Maya.

Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.