gemsmith 14.0.2 → 14.2.0

Sign up to get free protection for your applications and to get access to all the features.
metadata.gz.sig CHANGED
Binary file
data/README.md DELETED
@@ -1,383 +0,0 @@
1
- <p align="center">
2
- <img src="gemsmith.png" alt="Gemsmith Icon"/>
3
- </p>
4
-
5
- # Gemsmith
6
-
7
- [![Gem Version](https://badge.fury.io/rb/gemsmith.svg)](http://badge.fury.io/rb/gemsmith)
8
- [![Code Climate Maintainability](https://api.codeclimate.com/v1/badges/4fbf3375d2abb76a6f5d/maintainability)](https://codeclimate.com/github/bkuhlmann/gemsmith/maintainability)
9
- [![Code Climate Test Coverage](https://api.codeclimate.com/v1/badges/4fbf3375d2abb76a6f5d/test_coverage)](https://codeclimate.com/github/bkuhlmann/gemsmith/test_coverage)
10
- [![Circle CI Status](https://circleci.com/gh/bkuhlmann/gemsmith.svg?style=svg)](https://circleci.com/gh/bkuhlmann/gemsmith)
11
-
12
- A command line interface for smithing new Ruby gems.
13
-
14
- <!-- Tocer[start]: Auto-generated, don't remove. -->
15
-
16
- ## Table of Contents
17
-
18
- - [Features](#features)
19
- - [Screencasts](#screencasts)
20
- - [Requirements](#requirements)
21
- - [Setup](#setup)
22
- - [Install](#install)
23
- - [Configuration](#configuration)
24
- - [Existing Gems](#existing-gems)
25
- - [Usage](#usage)
26
- - [Command Line Interface (CLI)](#command-line-interface-cli)
27
- - [Rake](#rake)
28
- - [Tests](#tests)
29
- - [Security](#security)
30
- - [Git Signing Key](#git-signing-key)
31
- - [Gem Certificates](#gem-certificates)
32
- - [Private Gem Servers](#private-gem-servers)
33
- - [Gem Specification Metadata](#gem-specification-metadata)
34
- - [Gem Credentials](#gem-credentials)
35
- - [Promotion](#promotion)
36
- - [Troubleshooting](#troubleshooting)
37
- - [Versioning](#versioning)
38
- - [Code of Conduct](#code-of-conduct)
39
- - [Contributions](#contributions)
40
- - [License](#license)
41
- - [History](#history)
42
- - [Credits](#credits)
43
-
44
- <!-- Tocer[finish]: Auto-generated, don't remove. -->
45
-
46
- ## Features
47
-
48
- - Builds a gem skeleton with enhanced Bundler functionality.
49
- - Uses [Refinements](https://github.com/bkuhlmann/refinements) Ruby core library enhancements.
50
- - Uses [Versionaire](https://github.com/bkuhlmann/versionaire) for semantic versioning.
51
- - Uses [Runcom](https://github.com/bkuhlmann/runcom) for resource configuration management.
52
- - Uses [Milestoner](https://github.com/bkuhlmann/milestoner) for consistent project/gem versioning.
53
- - Uses [Pragmater](https://github.com/bkuhlmann/pragmater) for Ruby source pragma directives.
54
- - Uses [Tocer](https://github.com/bkuhlmann/tocer) for README table of contents generation.
55
- - Supports [Bundler Audit](https://github.com/rubysec/bundler-audit).
56
- - Supports [Circle CI](https://circleci.com).
57
- - Supports [Git Cop](https://github.com/bkuhlmann/git-cop).
58
- - Supports [GitHub](https://github.com).
59
- - Supports [Guard](https://github.com/guard/guard).
60
- - Supports [Pry](http://pryrepl.org).
61
- - Supports [Reek](https://github.com/troessner/reek).
62
- - Supports [RSpec](http://rspec.info).
63
- - Supports [Rubocop](https://github.com/rubocop-hq/rubocop).
64
- - Supports [Rubocop RSpec](https://github.com/rubocop-hq/rubocop-rspec).
65
- - Supports [Ruby on Rails](http://rubyonrails.org).
66
- - Supports [RubyGems Security](http://guides.rubygems.org/security).
67
- - Supports [SimpleCov](https://github.com/colszowka/simplecov).
68
- - Supports [Thor](https://github.com/erikhuda/thor).
69
- - Supports common settings and a structured layout for building gems.
70
- - Supports publishing to public or private gem servers.
71
- - Provides common documentation:
72
- - [README](README.md)
73
- - [CHANGES](CHANGES.md)
74
- - [CONTRIBUTING](CONTRIBUTING.md)
75
- - [CODE OF CONDUCT](CODE_OF_CONDUCT.md)
76
- - [LICENSE](LICENSE.md)
77
- - Aids in viewing source code of semantically versioned gems within your favorite editor.
78
- - Aids in viewing documentation of semantically versioned within your default browser.
79
-
80
- ## Screencasts
81
-
82
- [![asciicast](https://asciinema.org/a/277820.svg)](https://asciinema.org/a/277820)
83
-
84
- ## Requirements
85
-
86
- 1. A UNIX-based system.
87
- 1. [Ruby 2.7.x](https://www.ruby-lang.org).
88
- 1. [RubyGems](https://rubygems.org).
89
- 1. [Bundler](https://github.com/bundler/bundler).
90
-
91
- ## Setup
92
-
93
- ### Install
94
-
95
- Type the following to install:
96
-
97
- gem install gemsmith
98
-
99
- ### Configuration
100
-
101
- This gem can be configured via a global configuration:
102
-
103
- ~/.config/gemsmith/configuration.yml
104
-
105
- It can also be configured via [XDG](https://github.com/bkuhlmann/xdg) environment variables.
106
-
107
- The default configuration is as follows:
108
-
109
- :year: <current year>
110
- :github_user: "<Git config GitHub user>",
111
- :gem:
112
- :label: "Undefined"
113
- :name: "undefined"
114
- :path: "undefined"
115
- :class: "Undefined"
116
- :platform: "Gem::Platform::RUBY"
117
- :url: "https://github.com/<author>/<gem name>"
118
- :license: "MIT"
119
- :author:
120
- :name: "<Git config user name>"
121
- :email: "<Git config user email>"
122
- :url: ""
123
- :organization:
124
- :name: ""
125
- :url: ""
126
- :versions:
127
- :ruby: "<current Ruby version>"
128
- :rails: "5.1"
129
- :generate:
130
- :bundler_audit: true
131
- :circle_ci: false
132
- :cli: false
133
- :engine: false
134
- :git_cop: true
135
- :git_hub: true
136
- :guard: true
137
- :pry: true
138
- :reek: true
139
- :rspec: true
140
- :rubocop: true
141
- :simple_cov: true
142
- :security: false
143
- :publish:
144
- :sign: false
145
-
146
- Feel free to take this default configuration, modify, and save as your own custom
147
- `configuration.yml`.
148
-
149
- ### Existing Gems
150
-
151
- If you have gems that were not originally crafted by Gemsmith, you can add Gemsmith support to them
152
- by modifying the following files:
153
-
154
- Add the following to your gem's `*.gemspec` file:
155
-
156
- spec.add_development_dependency "gemsmith"
157
-
158
- Replace or add a modified version of the following to your gem's `Rakefile`:
159
-
160
- # frozen_string_literal: true
161
-
162
- begin
163
- require "gemsmith/rake/setup"
164
- rescue LoadError => error
165
- puts error.message
166
- end
167
-
168
- *NOTE: Ensure `require "bundler/gem_tasks"` is removed as Gemsmith replaces Bundler functionality.*
169
-
170
- With those changes, you can leverage the benefits of Gemsmith within your existing gem.
171
-
172
- ## Usage
173
-
174
- ### Command Line Interface (CLI)
175
-
176
- From the command line, type: `gemsmith --help`
177
-
178
- gemsmith -c, [--config] # Manage gem configuration.
179
- gemsmith -g, [--generate=GEM] # Generate new gem.
180
- gemsmith -h, [--help=COMMAND] # Show this message or get help for a command.
181
- gemsmith -o, [--open=GEM] # Open a gem in default editor.
182
- gemsmith -r, [--read=GEM] # Open a gem in default browser.
183
- gemsmith -v, [--version] # Show gem version.
184
-
185
- For more gem generation options, type: `gemsmith --help --generate`
186
-
187
- [--bundler-audit], [--no-bundler-audit] # Add Bundler Audit support.
188
- # Default: true
189
- [--circle-ci], [--no-circle-ci] # Add Circle CI support.
190
- [--cli], [--no-cli] # Add CLI support.
191
- [--engine], [--no-engine] # Add Rails Engine support.
192
- [--git-cop], [--no-git-cop] # Add Git Cop support.
193
- # Default: true
194
- [--git-hub], [--no-git-hub] # Add GitHub support.
195
- # Default: true
196
- [--guard], [--no-guard] # Add Guard support.
197
- # Default: true
198
- [--pry], [--no-pry] # Add Pry support.
199
- # Default: true
200
- [--reek], [--no-reek] # Add Reek support.
201
- # Default: true
202
- [--rspec], [--no-rspec] # Add RSpec support.
203
- # Default: true
204
- [--rubocop], [--no-rubocop] # Add Rubocop support.
205
- # Default: true
206
- [--security], [--no-security] # Add security support.
207
-
208
- ### Rake
209
-
210
- Once a gem skeleton has been created, the following tasks are available (i.e. `bundle exec rake
211
- -T`):
212
-
213
- rake build # Build example-0.1.0.gem package
214
- rake bundle:audit # Updates the ruby-advisory-db then runs bundle-audit
215
- rake clean # Clean gem artifacts
216
- rake code_quality # Run code quality checks
217
- rake git_cop # Run Git Cop
218
- rake install # Install example-0.1.0.gem package
219
- rake publish # Build, tag as 0.1.0 (unsigned), and push example-0.1.0.gem to RubyGems
220
- rake reek # Check for code smells
221
- rake rubocop # Run RuboCop
222
- rake rubocop:auto_correct # Auto-correct RuboCop offenses
223
- rake spec # Run RSpec code examples
224
- rake toc # Update Table of Contents (README)
225
-
226
- *NOTE: Some tasks might differ depending on what options you enabled/disabled during gem
227
- generation.*
228
-
229
- When building/testing your gem locally, a typical workflow is:
230
-
231
- 1. `bundle exec rake install`
232
- 1. Test your gem locally.
233
- 1. Repeat until satisfied.
234
-
235
- When satified with your gem, builds are green, and ready to publish, run:
236
-
237
- bundle exec rake publish
238
-
239
- ## Tests
240
-
241
- To test, run:
242
-
243
- bundle exec rake
244
-
245
- ## Security
246
-
247
- ### Git Signing Key
248
-
249
- To securely sign your Git tags, install and configure [GPG](https://www.gnupg.org):
250
-
251
- brew install gpg
252
- gpg --gen-key
253
-
254
- When creating your GPG key, choose these settings:
255
-
256
- - Key kind: RSA and RSA (default)
257
- - Key size: 4096
258
- - Key validity: 0
259
- - Real Name: `<your name>`
260
- - Email: `<your email>`
261
- - Passphrase: `<your passphrase>`
262
-
263
- To obtain your key, run the following and take the part after the forward slash:
264
-
265
- gpg --list-keys | grep pub
266
-
267
- Add your key to your global Git configuration in the `[user]` section. Example:
268
-
269
- [user]
270
- signingkey = <your GPG key>
271
-
272
- Now, when publishing your gems with Gemsmith (i.e. `bundle exec rake publish`), signing of your Git
273
- tag will happen automatically. You will be prompted for the GPG Passphrase each time but that is to
274
- be expected.
275
-
276
- ### Gem Certificates
277
-
278
- To create a certificate for your gems, run the following:
279
-
280
- cd ~/.ssh
281
- gem cert --build you@example.com
282
- chmod 600 gem-*.pem
283
-
284
- The resulting `*.pem` key files can be referenced via the `:private_key:` and `:public_key:` keys
285
- within the `~/.gemsmithrc` file.
286
-
287
- To learn more about gem certificates, read about RubyGems
288
- [Security](http://guides.rubygems.org/security).
289
-
290
- ## Private Gem Servers
291
-
292
- By default, the following Rake task will publish your gem to [RubyGems](https://rubygems.org):
293
-
294
- bundle exec rake publish
295
-
296
- You can change this behavior by adding metadata to your gemspec that will allow the Rake tasks,
297
- mentioned above, to publish your gem to an alternate/private gem server instead. This can be done by
298
- updating your gem specification and RubyGems credentials.
299
-
300
- ### Gem Specification Metadata
301
-
302
- Add the following metadata to your gemspec:
303
-
304
- Gem::Specification.new do |spec|
305
- spec.metadata = {
306
- "allowed_push_key" => "example_key",
307
- "allowed_push_host" => "https://gems.example.com"
308
- }
309
- end
310
-
311
- The gemspec metadata keys and values *must* be strings per the
312
- [RubyGems Specification](http://guides.rubygems.org/specification-reference/#metadata). Each key
313
- represents the following:
314
-
315
- - `allowed_push_key`: Provides a reference (look up) to the key defined the RubyGems credentials
316
- file so that sensitive credentials are not used within your gemspec.
317
- - `allowed_push_host`: Provides the URL of the private gem server to push your gem to.
318
-
319
- ### Gem Credentials
320
-
321
- With your gem specification metadata established, you are ready to publish your gem to a public or
322
- private server. If this is your first time publishing a gem and no gem credentials have been
323
- configured, you'll be prompted for them. Gem credentials are stored in the RubyGems
324
- `~/.gem/credentials` file. From this point forward, future gem publishing will use your stored
325
- credentials instead. Multiple credentials can be stored in the `~/.gem/credentials` file. Example:
326
-
327
- ---
328
- :rubygems_api_key: 2a0b460650e67d9b85a60e183defa376
329
- :example_key: "Basic dXNlcjpwYXNzd29yZA=="
330
-
331
- Should you need to delete a credential (due to a bad login/password for example), you can open the
332
- `~/.gem/credentials` in your default editor and remove the line(s) you don't need. Upon next publish
333
- of your gem, you'll be prompted for the missing credentials.
334
-
335
- ## Promotion
336
-
337
- Once your gem is released, let the world know about your accomplishment by posting an update to
338
- these sites:
339
-
340
- - [RubyFlow](http://www.rubyflow.com)
341
- - [Ruby Library Hunt](https://ruby.libhunt.com)
342
- - [RubyDaily](http://rubydaily.org)
343
- - [Awesome Ruby](https://awesome-ruby.com)
344
- - [Ruby Toolbox](https://www.ruby-toolbox.com)
345
- - [Ruby Community](https://www.ruby-lang.org/en/community)
346
-
347
- ## Troubleshooting
348
-
349
- When running `bundle exec rake install` or `bundle exec rake publish` with modified, staged, or
350
- uncommitted Git changes, the rake task will throw an error to this effect. When this occurs, it is
351
- recommended that you commit your changes or [stash](https://git-scm.com/docs/git-stash) them before
352
- proceeding.
353
-
354
- ## Versioning
355
-
356
- Read [Semantic Versioning](https://semver.org) for details. Briefly, it means:
357
-
358
- - Major (X.y.z) - Incremented for any backwards incompatible public API changes.
359
- - Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes.
360
- - Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes.
361
-
362
- ## Code of Conduct
363
-
364
- Please note that this project is released with a [CODE OF CONDUCT](CODE_OF_CONDUCT.md). By
365
- participating in this project you agree to abide by its terms.
366
-
367
- ## Contributions
368
-
369
- Read [CONTRIBUTING](CONTRIBUTING.md) for details.
370
-
371
- ## License
372
-
373
- Copyright 2011 [Alchemists](https://www.alchemists.io).
374
- Read [LICENSE](LICENSE.md) for details.
375
-
376
- ## History
377
-
378
- Read [CHANGES](CHANGES.md) for details.
379
-
380
- ## Credits
381
-
382
- Developed by [Brooke Kuhlmann](https://www.alchemists.io) at
383
- [Alchemists](https://www.alchemists.io).