jeweler 1.8.2 → 2.3.7

data/README.org

@@ -0,0 +1,374 @@
+/Jeweler maintenance has now shifted to Fred Mitchell/. I am now
+maintaining both Jeweler and its fork, juwelier. I will keep Jeweler at
+least functional with the latest Ruby releases, but put new features in
+Juwelier. Your input on this is more than welcome.
+
+* Jeweler: Craft the perfect RubyGem
+
+[[https://gitter.im/technicalpickles/jeweler?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge][[[https://badges.gitter.im/technicalpickles/jeweler.svg]]]]
+
+Jeweler provides the noble ruby developer with two primary features:
+
+-  a library for managing and releasing RubyGem projects
+-  a scaffold generator for starting new RubyGem projects
+
+PLEASE NOTE that if you are starting afresh, please use the successor
+[[https://github.com/flajann2/juwelier][Juwelier]] I (Fred Mitchell, flajann2) will be maintaining both Jeweler and Juwelier, but will be
+adding new features to Juwelier, and eventually "merge" this one into
+Juwelier after some namespace issues are dealt with.
+
+[[https://travis-ci.org/technicalpickles/jeweler][[[https://travis-ci.org/technicalpickles/jeweler.png]]]]
+[[https://coveralls.io/r/technicalpickles/jeweler][[[https://coveralls.io/repos/technicalpickles/jeweler/badge.png]]]]
+[[https://www.versioneye.com/ruby/jeweler/2.0.0][[[https://www.versioneye.com/ruby/jeweler/2.0.0/badge.png]]]]
+[[https://codeclimate.com/github/technicalpickles/jeweler][[[https://codeclimate.com/github/technicalpickles/jeweler/badges/gpa.svg]]]]
+
+** Hello, world
+
+Use RubyGems to install the heck out of jeweler to get started:
+
+#+BEGIN_EXAMPLE
+    $ gem install jeweler
+#+END_EXAMPLE
+
+With jeweler installed, you can use the =jeweler= command to generate a
+new project. For the most basic use, just give it a name:
+
+#+BEGIN_EXAMPLE
+    $ jeweler hello-gem
+#+END_EXAMPLE
+
+This requires some Git configuration (like name, email, GitHub account,
+etc), but =jeweler= will prompt along the way.
+
+Your new =hello-gem= gem is ready in the =hello-gem= directory. Take a
+peek, and you'll see several files and directories
+
+-  =Rakefile= setup for jeweler, running tests, generating
+   documentation, and releasing to
+   [[http://rubygems.org/][rubygems.org]]
+-  =README.rdoc= with contribution guidelines and copyright info
+   crediting you
+-  =LICENSE= with the MIT licensed crediting you
+-  =Gemfile= with development dependencies filled in
+-  =lib/hello-gem.rb= waiting for you to code
+-  =test/= containing a (failing) shoulda test suite
+   [[http://github.com/thoughtbot/shoulda][shoulda]]
+
+*** More =jeweler= options
+
+The =jeweler= command supports a lot of options. Mostly, they are for
+generating baked in support for this test framework, or that.
+
+Check out =jeweler --help= for the most up to date options.
+
+** Hello, rake tasks
+
+Beyond just editing source code, you'll be interacting with your gem
+using =rake= a lot. To see all the tasks available with a brief
+description, you can run:
+
+#+BEGIN_EXAMPLE
+    $ rake -T
+#+END_EXAMPLE
+
+You'll need a version before you can start installing your gem locally.
+The easiest way is with the =version:write= Rake task. Let's imagine you
+start with 0.1.0
+
+#+BEGIN_EXAMPLE
+    $ rake version:write MAJOR=0 MINOR=1 PATCH=0
+#+END_EXAMPLE
+
+You can now go forth and develop, now that there's an initial version
+defined. Eventually, you should install and test the gem:
+
+#+BEGIN_EXAMPLE
+    $ rake install
+#+END_EXAMPLE
+
+The =install= rake task builds the gem and =gem install=s it. You're all
+set if you're using [[http://rvm.beginrescueend.com/][RVM]], but you may
+need to run it with sudo if you have a system-installed ruby:
+
+#+BEGIN_EXAMPLE
+    $ sudo rake install
+#+END_EXAMPLE
+
+*** Releasing
+
+At last, it's time to [[http://shipitsquirrel.github.com/][ship it]]!
+Make sure you have everything committed and pushed, then go wild:
+
+#+BEGIN_EXAMPLE
+    $ rake release
+#+END_EXAMPLE
+
+This will automatically:
+
+-  Generate =hello-gem.gemspec= and commit it
+-  Use =git= to tag =v0.1.0= and push it
+-  Build =hello-gem-0.1.0.gem= and push it to
+   [[http://rubygems.org/gems/][rubygems.org]]
+
+=rake release= accepts REMOTE(default: =origin=), LOCAL\_BRANCH(default:
+=master=), REMOTE\_BRANCH(default: =master=) and BRANCH(default:
+master)as options.
+
+#+BEGIN_EXAMPLE
+    $ rake release REMOTE=upstream LOCAL_BRANCH=critical-security-fix REMOTE_BRANCH=v3
+#+END_EXAMPLE
+
+This will tag and push the commits on your local branch named
+=critical-security-fix= to branch named =v3= in remote named =upstream=
+(if you have commit rights on =upstream=) and release the gem.
+
+#+BEGIN_EXAMPLE
+    $ rake release BRANCH=v3
+#+END_EXAMPLE
+
+If both remote and local branches are the same, use =BRANCH= option to
+simplify. This will tag and push the commits on your local branch named
+=v3= to branch named =v3= in remote named =origin= (if you have commit
+rights on =origin=) and release the gem.
+
+*** Version bumping
+
+It feels good to release code. Do it, do it often. But before that, bump
+the version. Then release it. There's a few ways to update the version:
+
+#+BEGIN_EXAMPLE
+    # version:write like before
+    $ rake version:write MAJOR=0 MINOR=3 PATCH=0
+
+    # bump just major, ie 0.1.0 -> 1.0.0
+    $ rake version:bump:major
+
+    # bump just minor, ie 0.1.0 -> 0.2.0
+    $ rake version:bump:minor
+
+    # bump just patch, ie 0.1.0 -> 0.1.1
+    $ rake version:bump:patch
+#+END_EXAMPLE
+
+Then it's the same =release= we used before:
+
+#+BEGIN_EXAMPLE
+    $ rake release
+#+END_EXAMPLE
+
+** Customizing your gem
+
+If you've been following along so far, your gem is just a blank slate.
+You're going to need to make it colorful and full of metadata.
+
+You can customize your gem by updating your =Rakefile=. With a newly
+generated project, it will look something like this:
+
+#+BEGIN_EXAMPLE
+    require 'jeweler'
+    Jeweler::Tasks.new do |gem|
+      # gem is a Gem::Specification... see http://guides.rubygems.org/specification-reference/ for more options
+      gem.name = "whatwhatwhat"
+      gem.summary = %Q{TODO: one-line summary of your gem}
+      gem.description = %Q{TODO: longer description of your gem}
+      gem.email = "josh@technicalpickles.com"
+      gem.homepage = "http://github.com/technicalpickles/whatwhatwhat"
+      gem.authors = ["Joshua Nichols"]
+    end
+    Jeweler::RubygemsDotOrgTasks.new
+#+END_EXAMPLE
+
+It's crucial to understand the =gem= object is just a
+Gem::Specification. You can read up about it at
+[[http://guides.rubygems.org/specification-reference/][guides.rubygems.org/specification-reference]].
+This is the most basic way of specifying a gem, Jeweler-managed or not.
+Jeweler just exposes this to you, in addition to providing some
+reasonable defaults, which we'll explore now.
+
+*** Project information
+
+#+BEGIN_EXAMPLE
+    gem.name = "whatwhatwhat"
+#+END_EXAMPLE
+
+Every gem has a name. Among other things, the gem name is how you are
+able to =gem install= it.
+[[http://guides.rubygems.org/specification-reference/#name][Reference]]
+
+#+BEGIN_EXAMPLE
+    gem.summary = %Q{TODO: one-line summary of your gem}
+#+END_EXAMPLE
+
+This is a one line summary of your gem. This is displayed, for example,
+when you use =gem list --details= or view it on
+[[http://rubygems.org/gems/][rubygems.org]].
+
+#+BEGIN_EXAMPLE
+    gem.description = %Q{TODO: longer description of your gem}
+#+END_EXAMPLE
+
+Description is a longer description. Scholars ascertain that knowledge
+of where the description is used was lost centuries ago.
+
+#+BEGIN_EXAMPLE
+    gem.email = "josh@technicalpickles.com"
+#+END_EXAMPLE
+
+This should be a way to get a hold of you regarding the gem.
+
+#+BEGIN_EXAMPLE
+    gem.homepage = "http://github.com/technicalpickles/whatwhatwhat"
+#+END_EXAMPLE
+
+The homepage should have more information about your gem. The jeweler
+generator guesses this based on the assumption your code lives on
+[[http://github.com/][GitHub]], using your Git configuration to find
+your GitHub username. This is displayed by =gem list --details= and on
+rubygems.org.
+
+#+BEGIN_EXAMPLE
+    gem.authors = ["Joshua Nichols"]
+#+END_EXAMPLE
+
+Hey, this is you, the author (or me in this case). The =jeweler=
+generator also guesses this from your Git configuration. This is
+displayed by =gem list --details= and on rubygems.org.
+
+*** Files
+
+The quickest way to add more files is to =git add= them. Jeweler uses
+your Git repository to populate your gem's files by including added and
+committed and excluding =.gitignore=d. In most cases, this is reasonable
+enough.
+
+If you need to tweak the files, that's cool. Jeweler populates
+=gem.files= as a =Rake::FileList=. It's like a normal array, except you
+can =include= and =exclude= file globs:
+
+#+BEGIN_EXAMPLE
+    gem.files.exclude 'tmp' # exclude temporary directory
+    gem.files.include 'lib/foo/bar.rb' # explicitly include lib/foo/bar.rb
+#+END_EXAMPLE
+
+If that's not enough, you can just set =gem.files= outright
+
+#+BEGIN_EXAMPLE
+    gem.files = Dir.glob('lib/**/*.rb')
+#+END_EXAMPLE
+
+*** Dependencies
+
+Dependencies let you define other gems that your gem needs to function.
+=gem install your-gem= will install your-gem's dependencies along with
+it, and when you use your-gem in an application, the dependencies will
+be made available. Use =gem.add_dependency= to register them.
+[[http://guides.rubygems.org/specification-reference/#add_development_dependency][Reference]]
+
+#+BEGIN_EXAMPLE
+    gem.add_dependency 'nokogiri'
+#+END_EXAMPLE
+
+This will ensure a version of =nokogiri= is installed, but it doesn't
+require anything more than that. You can provide extra args to be more
+specific:
+
+#+BEGIN_EXAMPLE
+    gem.add_dependency 'nokogiri', '= 1.2.1' # exactly version 1.2.1
+    gem.add_dependency 'nokogiri', '>= 1.2.1' # greater than or equal to 1.2.1, ie, 1.2.1, 1.2.2, 1.3.0, 2.0.0, etc
+    gem.add_dependency 'nokogiri', '>= 1.2.1', '< 1.3.0' # greater than or equal to 1.2.1, but less than 1.3.0
+    gem.add_dependency 'nokogiri', '~> 1.2.1' # same thing, but more concise
+#+END_EXAMPLE
+
+When specifying which version is required, there's a bit of the
+condunrum. You want to allow the most versions possible, but you want to
+be sure they are compatible. Using =>= 1.2.1= is fine most of the time,
+except until the point that 2.0.0 comes out and totally breaks backwards
+the API. That's when it's good to use =~> 1.2.1=, which requires any
+version in the =1.2= family, starting with =1.2.1=.
+
+*** Executables
+
+Executables let your gem install shell commands. Just put any executable
+scripts in the =bin/= directory, make sure they are added using =git=,
+and Jeweler will take care of the rest.
+
+When you need more finely grained control over it, you can set it
+yourself:
+
+#+BEGIN_EXAMPLE
+    gem.executables = ['foo'] # note, it's the file name relative to `bin/`, not the project root
+#+END_EXAMPLE
+
+*** Versioning
+
+We discussed earlier how to bump the version. The rake tasks are really
+just convience methods for manipulating the =VERSION= file. It just
+contains a version string, like =1.2.3=.
+
+=VERSION= is a convention used by Jeweler, and is used to populate
+=gem.version=. You can actually set this yourself, and Jeweler won't try
+to override it:
+
+#+BEGIN_EXAMPLE
+    gem.version = '1.2.3'
+#+END_EXAMPLE
+
+A common pattern is to have this in a version constant in your library.
+This is convenient, because users of the library can query the version
+they are using at runtime.
+
+#+BEGIN_EXAMPLE
+    # in lib/foo/version.rb
+    class Foo
+      module Version
+        MAJOR = 1
+        MINOR = 2
+        PATCH = 3
+        BUILD = 'pre3'
+
+        STRING = [MAJOR, MINOR, PATCH, BUILD].compact.join('.')
+      end
+    end
+
+    # in Rakefile
+    require 'jeweler'
+    require './lib/foo/version.rb'
+    Jeweler::Tasks.new do |gem|
+      # snip
+      gem.version = Foo::Version::STRING
+    end
+#+END_EXAMPLE
+
+*** Rake tasks
+
+Jeweler lives inside of Rake. As a result, they are dear friends. But,
+that friendship doesn't interfere with typical Rake operations.
+
+That means you can define your own namespaces, tasks, or use third party
+Rake libraries without cause for concern.
+
+** Contributing to Jeweler
+
+-  Check out the latest master to make sure the feature hasn't been
+   implemented or the bug hasn't been fixed yet
+-  Ask on the [[http://groups.google.com/group/jeweler-rb][mailing
+   list]] for feedback on your proposal, to see if somebody else has
+   done it.
+-  Check out the
+   [[http://github.com/technicalpickles/jeweler/issues][issue tracker]]
+   to make sure someone already hasn't requested it and/or contributed
+   it
+-  Fork the project
+-  Start a feature/bugfix branch
+-  Commit and push until you are happy with your contribution
+-  Make sure to add tests for the feature/bugfix. This is important so I
+   don't break it in a future version unintentionally.
+-  Please try not to mess with the Rakefile, version, or history. If you
+   want to have your own version, or is otherwise necessary, that is
+   fine, but please isolate it to its own commit so I can cherry-pick
+   around it.
+
+** Copyright
+
+Copyright (c) 2008-2010 Josh Nichols. Copyright (c) 2016 Fred Mitchell.
+See LICENSE for details.

data/Rakefile

@@ -2,32 +2,34 @@
 
 require 'rubygems'
 require 'bundler'
+require 'semver'
+
+def s_version
+  SemVer.find.format "%M.%m.%p%s"
+end
 
 begin
-  Bundler.setup(:default, :development)
+  Bundler.setup(:default, :xzibit, :development)
 rescue Bundler::BundlerError => e
   $stderr.puts e.message
-  $stderr.puts "Run `bundle install` to install missing gems"
+  $stderr.puts 'Run `bundle install` to install missing gems'
   exit e.status_code
 end
 
-$LOAD_PATH.unshift('lib')
-
 require 'rake'
 require 'jeweler'
 
 Jeweler::Tasks.new do |gem|
-  gem.name = "jeweler"
-  gem.version = Jeweler::Version::STRING
-  gem.homepage = "http://github.com/technicalpickles/jeweler"
-  gem.summary = "Opinionated tool for creating and managing RubyGem projects"
-  gem.description = "Simple and opinionated helper for creating Rubygem projects on GitHub"
-  gem.license = "MIT"
-  gem.authors = ["Josh Nichols"]
-  gem.email = "josh@technicalpickles.com"
+  gem.name = 'jeweler'
+  gem.version = s_version
+  gem.homepage = 'http://github.com/technicalpickles/jeweler'
+  gem.summary = 'Opinionated tool for creating and managing RubyGem projects'
+  gem.description = 'Simple and opinionated helper for creating Rubygem projects on GitHub'
+  gem.required_ruby_version = '>= 2.2.0'
+  gem.license = 'MIT'
+  gem.authors = ["Fred Mitchell", "Josh Nichols", "Yusuke Murata"]
+  gem.email = ["fred.mitchell@gmx.de", "fred.mitchell@gmx.com", "info@muratayusuke.com"]
   gem.files.include %w(lib/jeweler/templates/.document lib/jeweler/templates/.gitignore)
-
-  # dependencies defined in Gemfile
 end
 
 Jeweler::RubygemsDotOrgTasks.new
@@ -46,7 +48,7 @@ namespace :test do
   task :gemspec_dup do
     gemspec = Rake.application.jeweler.gemspec
     dupped_gemspec = gemspec.dup
-    cloned_gemspec = gemspec.clone
+    _cloned_gemspec = gemspec.clone
     puts gemspec.to_ruby
     puts dupped_gemspec.to_ruby
   end
@@ -54,28 +56,21 @@ end
 
 require 'yard'
 YARD::Rake::YardocTask.new do |t|
-  t.files   = FileList['lib/**/*.rb'].exclude('lib/jeweler/templates/**/*.rb')
-end
-
-require 'rcov/rcovtask'
-Rcov::RcovTask.new(:rcov => :check_dependencies) do |rcov|
-  rcov.libs << 'test'
-  rcov.pattern = 'test/**/test_*.rb'
+  t.files = FileList['lib/**/*.rb'].exclude('lib/jeweler/templates/**/*.rb')
 end
 
 require 'cucumber/rake/task'
 Cucumber::Rake::Task.new(:features) do |features|
-  features.cucumber_opts = "features --format progress"
+  features.cucumber_opts = 'features --format progress'
 end
 namespace :features do
   Cucumber::Rake::Task.new(:pretty) do |features|
-    features.cucumber_opts = "features --format progress"
+    features.cucumber_opts = 'features --format progress'
   end
 end
 
-if ENV["RUN_CODE_RUN"] == "true"
-  task :default => [:test, :features]
+if ENV['RUN_CODE_RUN'] == 'true'
+  task default: [:test, :features]
 else
-  task :default => :test
+  task default: :test
 end
-

data/bin/jeweler

@@ -1,3 +1,4 @@
+#!/usr/bin/env ruby
 # Don't try to run this binary directory. Instead:
 # * `bundle exec jeweler` if doing jeweler development
 # * `bundle exec jeweler` if part of a bundle

data/features/generator/gemfile.feature

@@ -23,6 +23,7 @@ Feature: generated Gemfiel
     And 'Gemfile' uses the gemcutter source
     And 'Gemfile' has a development dependency on 'bundler'
     And 'Gemfile' has a development dependency on the current version of jeweler
+    And 'Gemfile' has a development dependency on 'simplecov'
     And 'Gemfile' has a development dependency on 'rcov'
     And 'Gemfile' has a development dependency on 'rdoc'
     And 'Gemfile' does not have a development dependency on 'yard'

data/features/generator/test.feature

@@ -13,7 +13,7 @@ Feature: generated test or spec
     Given a working directory
     And I have configured git sanely
     When I generate a minitest project named 'the-perfect-gem' that is 'zomg, so good'
-    Then 'test/test_the-perfect-gem.rb' should define 'TestThePerfectGem' as a subclass of 'MiniTest::Unit::TestCase'
+    Then 'test/test_the-perfect-gem.rb' should define 'TestThePerfectGem' as a subclass of 'MiniTest::Test'
 
   Scenario: rspec
     Given a working directory
@@ -51,4 +51,4 @@ Feature: generated test or spec
     Given a working directory
     And I have configured git sanely
     When I generate a shindo project named 'the-perfect-gem' that is 'zomg, so good'
-    Then 'tests/the-perfect-gem_tests.rb' should have tests for 'ThePerfectGem'
+    Then 'tests/the-perfect-gem_tests.rb' should have tests for 'ThePerfectGem'

data/features/step_definitions/debug_steps.rb

@@ -3,4 +3,3 @@ Then /^I debug$/ do
   breakpoint
   0
 end
-

data/features/step_definitions/filesystem_steps.rb

@@ -21,7 +21,7 @@ Given /^I use the jeweler command to generate the "([^"]+)" project in the worki
 end
 
 Given /^"([^"]+)" does not exist$/ do |file|
-  assert ! File.exists?(File.join(@working_dir, file))
+  assert !File.exist?(File.join(@working_dir, file))
 end
 
 When /^I run "([^"]+)" in "([^"]+)"$/ do |command, directory|
@@ -33,7 +33,7 @@ When /^I run "([^"]+)" in "([^"]+)"$/ do |command, directory|
   assert File.directory?(full_path), "#{full_path} is not a directory"
 
   @stdout = `cd #{full_path} && #{command}`
-  @exited_cleanly = $?.exited?
+  @exited_cleanly = $CHILD_STATUS.exited?
 end
 
 Then /^the updated version, (.*), is displayed$/ do |version|
@@ -67,4 +67,3 @@ Given /^"VERSION" contains "([^\"]*)"$/ do |expected|
   version = File.read(File.join(@working_dir, @name, 'VERSION')).chomp
   assert_equal expected, version
 end
-