Rubysmith is a command line interface for smithing Ruby projects.

This gem is useful in situations in which you need something more sophisticated than a Bundler Inline script but less than a Gemsmith gem. Rubysmith is the foundation of Gemsmith and provides much of the same functionality as Gemsmith but is solely tailored for pure Ruby projects. Again, this is a great tool for spiking quick Ruby implementations, sharing code snippets with others, or building full blown Ruby projects for collaboration with others.

Table of Contents

• Features
• Requirements
• Setup
• Usage
  • Command Line Interface (CLI)
    • Build
      • Amazing Print
      • Bootsnap
      • Caliber
      • Circle CI
      • Citation
      • Community
      • Code of Conduct
      • Console
      • Contributions
      • Developer Certificate of Origin
      • Debug
      • Docker
      • Development Containers
      • Funding
      • Git
      • GitHub
      • GitHub CI
      • Git Lint
      • Guard
      • IRB Kit
      • License
      • Maximum
      • Minimum
      • Rake
      • Readme
      • Reek
      • Refinements
      • RSpec
      • Repl Type Completor (RTC)
      • Setup
      • SimpleCov
      • Versions
      • Zeitwerk
  • Configuration
    • Author
    • Build
    • Citations
    • Documentation
    • License
      • Apache
      • Fair Source
      • Hippocratic
      • MIT
    • Organization
    • Project
    • Repository
• Development
• Tests
• License
• Security
• Code of Conduct
• Contributions
• Developer Certificate of Origin
• Versions
• Community
• Credits

Features

• Builds a Ruby project skeleton for custom design and development.

• Uses Runcom for resource configuration management.

• Uses Pragmater for Ruby source pragma directives.

• Supports Amazing Print.

• Supports Caliber.

• Supports Circle CI.

• Supports Citations (ORCID).

• Supports console script for local development.

• Supports Debug.

• Supports Development Containers.

• Supports Docker.

• Supports Git.

• Supports GitHub.

• Supports Git Lint.

• Supports IRB Kit.

• Supports Rake.

• Supports Reek.

• Supports Refinements.

• Supports RSpec.

• Supports ReplTypeCompletor.

• Supports setup script for project setup.

• Supports SimpleCov.

• Supports Zeitwerk.

• Supports common settings and a structured layout for building projects.

• Provides common documentation.

Requirements

1. A UNIX-based system.

2. Ruby.

Setup

To install with security, run:

# 💡 Skip this line if you already have the public certificate installed.
gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
gem install rubysmith --trust-policy HighSecurity

To install without security, run:

gem install rubysmith

Usage

Command Line Interface (CLI)

From the command line, type: rubysmith --help

Build

The core functionality of this gem centers around the --build command and associated options (flags). The build options allow you to further customize the kind of project you want to build. Most build options are enabled by default. Example:

rubysmith build --name demo

Running the above will generate a new demo Ruby project. Should you wish to disable specific options, you can use --no-* prefixes. Example:

rubysmith build --name demo --no-debug --no-reek

With the above example, both Debug and Reek support would have been disabled when building the demo project. Taking this a step further, you can also use the --min option to generate a project with bare minimum of options. Example:

rubysmith build --name demo --min

The above is the same as building with all options disabled. This is handy in situations where you need to quickly script something up for sharing with others yet still want to avoid using a Bundler Inline script so gem dependencies are not installed each time the code is run.

As shown earlier, you can combine options but be aware that order matters. Take the following, for example, where both minimum and maximum options are used in conjunction with other options:

rubysmith build --name demo --min --zeitwerk
rubysmith build --name demo --max --no-debug

With the above examples, the first line will disable all options except Zeitwerk while the second line will enable all options except Debug. This can be a handy way to build a new project with all options either disabled or enabled with only a few select options modified. To have specific options enabled/disabled every time, you can edit your global configuration for making these settings permanent (see below for details).

There is a lot of flexibility when building a new project through the various build options. I’ll walk you through each so you can better understand why you’d want to enable or disable them.

Amazing Print

The --amazing_print option allows you to build your project with the Amazing Print gem for debugging purposes and is a handy debugging tool when inspecting your Ruby objects and printing details in a quick to read format.

Bootsnap

The --bootsnap option allows you to build your project with the Bootsnap gem for improved performance. This is best used for pure, non-gem, Ruby projects and/or web applications in general.

Caliber

The --caliber option allows you to build your project with the Caliber gem so you have an immediate working — and high quality — RuboCop configuration. Read the Caliber documentation for further customization. This adds the following files when enabled:

├── bin
│  ├── rubocop
├── .config
│  └── rubocop
│     └── config.yml

Circle CI

The --circle_ci option allows you to build your project with Circle CI configured so you can get your project building as quickly as possible. This adds the following file when enabled:

├── .circleci
│  └── config.yml

Citation

The --citation option allows you to add a citation file to your project so you can help the research community cite your work in their studies if your project is used. This adds the following file when enabled:

├── CITATION.cff

Community

The --community option allows you to link to your open source community, organization, or group chat to help with community engagement of your work. The link is added to the README file when enabled.

Code of Conduct

The --conduct option allows you to link to your Code of Conduct to encourage good community participation. Regardless of whether you have a community or not, the code of conduct is good to encourage in general. The link is added to the README file when enabled.

Console

The --console option allows you to add a console script for local development. So instead of typing irb, you can type bin/console and get an IRB session with all of your project’s code loaded. This adds the following file when enabled:

├── bin
│  ├── console

Contributions

The --contributions option allows you to link to contributing documentation so people know to contribute back to your work. The link is added to the README file when enabled.

Developer Certificate of Origin

The --dcoo option allows to you add Developer Certificate of Origin documentation so all contributors are aware of how their contributions are applied in terms of ownership, copyright, and licensing. The link is added to the README file when enabled.

ℹ️ This is disabled by default but will be enabled by default in the next major version.

Debug

The --debug option allows you add the Debug gem to your project for debugging your code by setting breakpoints, remotely connecting to running code, and much more.

Docker

The --docker option allows you add Docker to your project so you can build and deploy a production image of your software. When enabled, these files will appear in your project:

├── bin
│  ├── docker
│  │  ├── build       # Use to build your production image for local use.
│  │  ├── console     # Use to interact with your production image.
│  │  └── entrypoint  # Conditionally enables jemalloc support.
├── .dockerignore     # Defines the files/folders Docker should ignore.
├── Dockerfile        # Defines how to build your production image.

Development Containers

The --devcontainer option allows you add Development Containers support to your project so you can develop locally by running your project within a Docker container. When enabled, these files will be added to your project:

├── .devcontainer
│  ├── compose.yaml       # Your Docker Compose configuration.
│  ├── devcontainer.json  # Your Developer Container configuration.
│  └── Dockerfile         # The steps for building your development environment.

ℹ️ The Dockerfile uses the Docker Alpine Ruby base image so you have a small but functional image. This base image can be easily be swapped out with a base image you prefer.

Funding

The --funding option allows you add a GitHub funding configuration to your project so you can attract sponsors. This option doesn’t require use of the --git_hub option but is encouraged. This adds the following file when enabled:

├── .github
│  ├── FUNDING.yml

Git

The --git option allows you add Git repository support. Includes Git Safe functionality so you don’t have to prefix commands with the bin/ path prefix. Instead, you can call the command directly (assuming you have configured your Dotfiles accordingly).

GitHub

The --git_hub option allows you add GitHub templates to your project for issues and pull requests. This adds the following fhile when enabled:

├── .github
│  ├── ISSUE_TEMPLATE.md
│  └── PULL_REQUEST_TEMPLATE.md

GitHub CI

The --git_hub_ci option allows you to build your project with GitHub Actions configured so you can get your project building as quickly as possible. This adds the following file when enabled:

├── .github
│  ├── workflows
│  │  └── ci.yml

Git Lint

The --git-lint option allows you to add the Git Lint gem to your project to ensure you are crafting your Git commits in a consistent and readable manner.

Guard

⚠️ This is deprecated and will be removed in the next major version.

The --guard option allows you add the Guard gem to your project for rapid red, green, refactor development cycles.

IRB Kit

The --irb-kit option allows you add the IRB Kit gem to your project for additional extensions you can use within IRB to improve your workflow.

License

The --license option ensures you build your project with a license.

Maximum

The --max option allows you to build your project with all options enabled. This is a quick way to build a new project without having to pick and choose.

Minimum

The --min option allows you to build your project with all options disabled. This is a quick way to build a new project with the bare minimum of support which is a one step above reaching for a Bundler Inline script.

Rake

The --rake option allows you to add the Rake gem for quickly crafting build scripts. This adds the following files to your project:

├── bin
│  ├── rake
├── Rakefile

Readme

The --readme option allows you to add README documentation to your project.

Reek

The --reek option allows you add the Reek gem to your project for code smell and code quality support. This adds the .reek.yml configuration to your project.

Refinements

The --refinements option allows you to add the Refinements gem to your project which enhances Ruby core objects without monkey patching your code.

RSpec

The --rspec option allows you add the RSpec gem to your project for defining your project specifications and have a framework for testing your code. This adds the following files to your project:

├── bin
│  ├── rspec
├── spec
│  ├── lib
│  │  └── <your project name>_spec.rb
│  ├── support
│  │  └── shared_contexts
│  │     └── temp_dir.rb
│  └── spec_helper.rb

Repl Type Completor (RTC)

The --rtc option allows you add the Repl Type Completor gem to your project for improved type completion when using IRB.

Setup

The --setup option allows you to configure you project with automated setup instructions so anyone new to your project can quickly get started by running the bin/setup script. This adds the following file to your project:

│  └── setup

SimpleCov

The --simple_cov option allows you add the SimpleCov gem to your project to provide full analysis of your project’s code quality and/or find code that is unused.

Versions

The --versions option allows you add a VERSIONS file to your project to provide details about all published versions of your project.

Zeitwerk

The --zeitwerk option allows you add the Zeitwerk gem to your project so you can reduce the maintenance burden of managing requirements when adding new objects to your project.

This includes having access to your project’s Zeitwerk loader for inspection and debugging purposes. This means if you built a Demo project, you’d immediately have access to your project’s loader via Demo.loader when using the project console (i.e. bin/console, assuming you built your project with the --console flag enabled which is default behavior).

Configuration

This gem can be configured via a global configuration:

$HOME/.config/rubysmith/configuration.yml

It can also be configured via XDG/Runcom environment variables. The default configuration is as follows:

author:
  handle: undefined
  uri: "%<organization_uri>s/team/%<author_handle>s"
build:
  amazing_print: true
  bootsnap: false
  caliber: true
  circle_ci: false
  citation: true
  cli: false
  community: false
  conduct: true
  console: true
  contributions: true
  dcoo: false
  debug: true
  devcontainer: false
  docker: false
  funding: false
  git: true
  git_hub: false
  git_hub_ci: false
  git_lint: true
  guard: false
  irb_kit: true
  license: true
  maximum: false
  minimum: false
  rake: true
  readme: true
  reek: true
  refinements: true
  rspec: true
  rtc: true
  security: true
  setup: true
  simple_cov: true
  versions: true
  zeitwerk: true
citation:
  affiliation: "%<organization_label>s"
  message: Please use the following metadata when citing this project in your work.
documentation:
  format: "adoc"
license:
  label: Hippocratic
  name: hippocratic
  version: "2.1"
organization:
  uri: https://undefined.io
project:
  uri:
    community: "%<organization_uri>s/community"
    conduct: "%<organization_uri>s/policies/code_of_conduct"
    contributions: "%<organization_uri>s/policies/contributions"
    dcoo: "%<organization_uri>s/policies/developer_certificate_of_origin"
    download: "https://rubygems.org/gems/%<project_name>s"
    funding: "%<repository_uri>s/sponsors/%<repository_handle>s"
    home: "%<organization_uri>s/projects/%<project_name>s"
    issues: "%<repository_uri>s/%<repository_handle>s/%<project_name>s/issues"
    license: "%<organization_uri>s/policies/license"
    security: "%<organization_uri>s/policies/security"
    source: "%<repository_uri>s/%<repository_handle>s/%<project_name>s"
    versions: "%<organization_uri>s/projects/%<project_name>s/versions"
  version: 0.0.0
repository:
  handle: undefined
  uri: https://github.com

By customizing your configuration, you can change Rubysmith’s default behavior when building projects. This is a great way to define your own specialized settings other than what is provided by default. This is also a handy way to provide additional information needed for some of the build options.

You’ll also notice some of the values use String Formats which means you can use any fully qualified key as a string specifier for supported keys like those found in the author and project sections.

Each section of the configuration is explained below.

Author

Author information is used when generating project documentation and is recommended you fill this information in before building a project. Example:

author:
  email: jsmith@example.com
  family_name: Smith
  given_name: Jill
  author_uri:  # Requires being supplied.

If your global Git configuration is properly configured, your given name; family name; and email will be used by default. Should you not want to defer to Git, you can supply custom values as desired. The URI is the only value that can’t be automatically computed for you.

Build

All build options only accept booleans values and can be customized as desired. When changing your build options, they will dynamically render when displaying usage (i.e. rubysmith --help). All of these options have been explained in greater detail in the Usage section.

ℹ️ The cli option is provided to support Gemsmith but is not, currently, used by this project.

Citations

This section allows you to configure your ORCID citation information used by the research community.

citation:
  affiliation:  # Defaults to organization label (see above).
  message:      # Defaults to supplied message (see above).
  orcid:        # Defaults to https://orcid.org/ when no ID is supplied.

Your author, project, and license information will be used when building this file.

Documentation

Use this section to define the kind of documentation you want generated for your project. The following options are available:

• adoc: Uses ASCII Doc format.

• md: Uses Markdown format.

License

Use this section to define the license you want to use for your project. When picking a license, you can supply the appropriate label and version in addition to the name. The name is the only value you can’t customize. The following details all supported licenses.

Apache

To use the Apache license, apply this configuration:

license:
  label: "Apache"
  name: "apache"
  version: "2.0"

Fair Source

To use the Fair Source license, apply this configuration:

license:
  label: "Fair Source"
  name: "fair"
  version: "FSL-1.1-Apache-2.0"

Hippocratic

To use the Hippocratic license, apply this configuration:

license:
  label: "Hippocratic"
  name: "hippocratic"
  version: "2.1"

ℹ️ This is the default license unless you customize.

MIT

To use the MIT license, apply this configuration:

license:
  label: "MIT"
  name: "mit"
  version: ""

Organization

Use this section to define organization specific information. This is useful for information that isn’t project specific but related to all projects within your organization. You’ll want — highly recommended — to supply configuration details. For example, here’s what a fictional organization might look like:

organization:
  label: ACME
  uri: https://acme.io

Project

There are two sub-categories within this section: URIs and version. The URIs allow you to link to specific documentation related to your project. You’ll want to customize these URIs since they are used for documentation, citations, and general project information. Some of the URIs are also used by the Gemsmith gem.

One powerful feature of this configuration is that you can use %<project_name>s as a placeholder anywhere in your URIs and Rubysmith will ensure your place holder is replaced with your project name when generating a new project. Example:

# Configuration
https://www.example.com/%<project_name>s

# Command
rubysmith build --name demo

# Actual (computed result)
https://www.example.com/demo

As for the version key, this defines the default version of newly created projects. 0.0.0 is the default but you can use a higher version number like 0.1.0 or even 1.0.0 if you are super confident in your work. That said, a lower the number is recommended when building your initial project which is why 0.0.0 is the default.

Repository

Your repository handle is the handle you setup when creating your account (i.e. https://github.com/<your_handle>). This information is used for template, funding, and/or URI construction purposes. These are the defaults but you’ll want to customize to reflect the service you are using:

repository:
  handle: undefined
  uri: https://github.com

Development

To contribute, run:

git clone https://github.com/bkuhlmann/rubysmith
cd rubysmith
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Tests

To test, run:

bin/rake

License

Security

Code of Conduct

Contributions

Developer Certificate of Origin

Versions

Community

Credits

• Built with Gemsmith.

• Engineered by Brooke Kuhlmann.