Skip to content
Newer
Older
100644 209 lines (135 sloc) 7.71 KB
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 15, 2009
1 # Jeweler: Craft the perfect RubyGem
9b2d9c2 @technicalpickles Documentation, yo. Added gemspec:validate.
authored Oct 12, 2008
2
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 16, 2009
3 Jeweler provides two things:
9b2d9c2 @technicalpickles Documentation, yo. Added gemspec:validate.
authored Oct 12, 2008
4
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 16, 2009
5 * Rake tasks for managing gems and versioning of a <a href="http://github.com">GitHub</a> project
bea2b30 @priteau Fix some typos and remove trailing whitespace in README
priteau authored Nov 18, 2009
6 * A generator for creating/kickstarting a new project
9b2d9c2 @technicalpickles Documentation, yo. Added gemspec:validate.
authored Oct 12, 2008
7
a69ae84 @technicalpickles Updated links section, moved to top.
authored Apr 29, 2009
8 ## Quick Links
9
10 * [Wiki](http://wiki.github.com/technicalpickles/jeweler)
1b67a1a @technicalpickles Added link to README
authored Nov 2, 2009
11 * [Mailing List](http://groups.google.com/group/jeweler-rb)
a69ae84 @technicalpickles Updated links section, moved to top.
authored Apr 30, 2009
12 * [Bugs](http://github.com/technicalpickles/jeweler/issues)
13 * [Donate](http://pledgie.org/campaigns/2604)
14
258d8ea @technicalpickles Updated README to include install instructions.
authored Feb 21, 2009
15 ## Installing
16
17 # Install the gem:
e9bcc06 @technicalpickles Prefer using rubyforge gem instead of github.
authored Apr 5, 2009
18 sudo gem install jeweler
bea2b30 @priteau Fix some typos and remove trailing whitespace in README
priteau authored Nov 18, 2009
19
00f818b @technicalpickles readme and changelog updates.
authored Mar 5, 2009
20 ## Using in an existing project
8dc41f1 @namelessjon Cleaned eol whitespace
namelessjon authored Nov 15, 2008
21
ee0d9c4 @technicalpickles Fixed some typos that were pointed out.
authored Apr 2, 2009
22 It's easy to get up and running. Update your Rakefile to instantiate a `Jeweler::Tasks`, and give it a block with details about your project.
9b2d9c2 @technicalpickles Documentation, yo. Added gemspec:validate.
authored Oct 12, 2008
23
e215e49 @technicalpickles Updated suggested usage (begin/rescue loading jeweler).
authored Oct 12, 2008
24 begin
25 require 'jeweler'
ee0d9c4 @technicalpickles Fixed some typos that were pointed out.
authored Apr 2, 2009
26 Jeweler::Tasks.new do |gemspec|
27 gemspec.name = "the-perfect-gem"
1aecac1 @technicalpickles zomg, so much doc updates.
authored Nov 18, 2009
28 gemspec.summary = "One line summary of your gem"
29 gemspec.description = "A different and possibly longer explanation of"
ee0d9c4 @technicalpickles Fixed some typos that were pointed out.
authored Apr 2, 2009
30 gemspec.email = "josh@technicalpickles.com"
31 gemspec.homepage = "http://github.com/technicalpickles/the-perfect-gem"
32 gemspec.authors = ["Josh Nichols"]
e215e49 @technicalpickles Updated suggested usage (begin/rescue loading jeweler).
authored Oct 12, 2008
33 end
34 rescue LoadError
138c87b Fixed sample message for missing jeweler.
unknown authored Nov 7, 2009
35 puts "Jeweler not available. Install it with: sudo gem install jeweler"
d8fa2f9 @technicalpickles Added README.
authored Oct 11, 2008
36 end
8dc41f1 @namelessjon Cleaned eol whitespace
namelessjon authored Nov 15, 2008
37
e633cbf @technicalpickles Updated REAMDE to include link to new wiki page.
authored Apr 5, 2009
38 The yield object here, `gemspec`, is a `Gem::Specification` object. See the [Customizing your project's gem specification](http://wiki.github.com/technicalpickles/jeweler/customizing-your-projects-gem-specification) for more details about how you can customize your gemspec.
8dc41f1 @namelessjon Cleaned eol whitespace
namelessjon authored Nov 15, 2008
39
00f818b @technicalpickles readme and changelog updates.
authored Mar 5, 2009
40 ## Using to start a new project
8dc41f1 @namelessjon Cleaned eol whitespace
namelessjon authored Nov 15, 2008
41
035a6d0 @msassak Fix link to GitHub help on setting username and email address
msassak authored Aug 31, 2009
42 Jeweler provides a generator. It requires you to [setup your name and email for git](http://help.github.com/git-email-settings/) and [your username and token for GitHub](http://github.com/guides/local-github-config).
d8fa2f9 @technicalpickles Added README.
authored Oct 12, 2008
43
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 16, 2009
44 jeweler the-perfect-gem
d8fa2f9 @technicalpickles Added README.
authored Oct 12, 2008
45
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 16, 2009
46 This will prepare a project in the 'the-perfect-gem' directory, setup to use Jeweler.
d8fa2f9 @technicalpickles Added README.
authored Oct 12, 2008
47
1aecac1 @technicalpickles zomg, so much doc updates.
authored Nov 18, 2009
48 It supports a number of options. Here's a taste, but `jeweler --help` will give you the most up-to-date listing:
d8fa2f9 @technicalpickles Added README.
authored Oct 12, 2008
49
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 16, 2009
50 * --create-repo: in addition to preparing a project, it create an repo up on GitHub and enable RubyGem generation
195a6cf @technicalpickles Updated documentation.
authored Feb 3, 2009
51 * --testunit: generate test_helper.rb and test ready for test/unit
bea2b30 @priteau Fix some typos and remove trailing whitespace in README
priteau authored Nov 18, 2009
52 * --minitest: generate test_helper.rb and test ready for minitest
195a6cf @technicalpickles Updated documentation.
authored Feb 3, 2009
53 * --shoulda: generate test_helper.rb and test ready for shoulda (this is the default)
54 * --rspec: generate spec_helper.rb and spec ready for rspec
55 * --bacon: generate spec_helper.rb and spec ready for bacon
53ada0f @ddollar Added support for releasing to gemcutter [#27].
ddollar authored Aug 13, 2009
56 * --gemcutter: setup releasing to gemcutter
cc66671 Fixed typo in README about rubyforge.
Marc-Andre Lafortune authored Apr 1, 2009
57 * --rubyforge: setup releasing to rubyforge
d8fa2f9 @technicalpickles Added README.
authored Oct 12, 2008
58
4bc8636 @technicalpickles Updated documentation and changelog.
authored Mar 30, 2009
59 ### Default options
60
61 Jeweler respects the JEWELER_OPTS environment variable. Want to always use RSpec, and you're using bash? Add this to ~/.bashrc:
62
63 export JEWELER_OPTS="--rspec"
64
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 16, 2009
65 ## Gemspec
d8fa2f9 @technicalpickles Added README.
authored Oct 12, 2008
66
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 16, 2009
67 Jeweler handles generating a gemspec file for your project:
d8fa2f9 @technicalpickles Added README.
authored Oct 12, 2008
68
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 16, 2009
69 rake gemspec
d8fa2f9 @technicalpickles Added README.
authored Oct 12, 2008
70
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 16, 2009
71 This creates a gemspec for your project. It's based on the info you give `Jeweler::Tasks`, the current version of your project, and some defaults that Jeweler provides.
9b2d9c2 @technicalpickles Documentation, yo. Added gemspec:validate.
authored Oct 12, 2008
72
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 16, 2009
73 ## Gem
8e8fd3d @technicalpickles Do some guarding against strings being in the yaml.
authored Oct 13, 2008
74
1aecac1 @technicalpickles zomg, so much doc updates.
authored Nov 18, 2009
75 Jeweler gives you tasks for building and installing your gem.
76
77 rake install
78
79 To build the gem (which will end up in `pkg`), run:
8e8fd3d @technicalpickles Do some guarding against strings being in the yaml.
authored Oct 14, 2008
80
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 16, 2009
81 rake build
1aecac1 @technicalpickles zomg, so much doc updates.
authored Nov 18, 2009
82
bea2b30 @priteau Fix some typos and remove trailing whitespace in README
priteau authored Nov 18, 2009
83 To install the gem (and build if necessary), i.e. using gem install, run:
1aecac1 @technicalpickles zomg, so much doc updates.
authored Nov 18, 2009
84
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 16, 2009
85 rake install
9b2d9c2 @technicalpickles Documentation, yo. Added gemspec:validate.
authored Oct 12, 2008
86
1aecac1 @technicalpickles zomg, so much doc updates.
authored Nov 18, 2009
87 Note, this does not use `sudo` to install it, so if your ruby setup needs that, you should prefix it with sudo:
88
89 sudo rake install
90
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 16, 2009
91 ## Versioning
d8fa2f9 @technicalpickles Added README.
authored Oct 12, 2008
92
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 16, 2009
93 Jeweler tracks the version of your project. It assumes you will be using a version in the format `x.y.z`. `x` is the 'major' version, `y` is the 'minor' version, and `z` is the patch version.
d8fa2f9 @technicalpickles Added README.
authored Oct 12, 2008
94
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 16, 2009
95 Initially, your project starts out at 0.0.0. Jeweler provides Rake tasks for bumping the version:
8dc41f1 @namelessjon Cleaned eol whitespace
namelessjon authored Nov 15, 2008
96
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 16, 2009
97 rake version:bump:major
98 rake version:bump:minor
99 rake version:bump:patch
8dc038d @technicalpickles Added example for rdoc and testing.
authored Oct 12, 2008
100
bea2b30 @priteau Fix some typos and remove trailing whitespace in README
priteau authored Nov 18, 2009
101 You can also programmatically set the version if you wish. Typically, you use this to have a module with the version info so clients can access it. The only downside here is you no longer can use the version:bump tasks.
a8ac9ce @bryanlarsen Document Rakefile-specified version numbers.
bryanlarsen authored Oct 13, 2009
102
1970959 @agrimm Added missing slash in code example.
agrimm authored Nov 7, 2009
103 require File.dirname(__FILE__) + "/lib/my_project/version.rb"
a8ac9ce @bryanlarsen Document Rakefile-specified version numbers.
bryanlarsen authored Oct 12, 2009
104
ee4cbea @agrimm Fixed error in method name. Made block variable names more consistent.
agrimm authored Nov 7, 2009
105 Jeweler::Tasks.new do |gemspec|
106 gemspec.version = MyProject::VERSION
a8ac9ce @bryanlarsen Document Rakefile-specified version numbers.
bryanlarsen authored Oct 12, 2009
107 # more stuff
108 end
109
1aecac1 @technicalpickles zomg, so much doc updates.
authored Nov 18, 2009
110 ### Prerelease versioning
111
112 Major, minor, and patch versions have a distant cousin: build. You can use this to add an arbitrary (or you know, regular type) version. This is particularly useful for prereleases.
113
114 You have two ways of doing this:
115
bea2b30 @priteau Fix some typos and remove trailing whitespace in README
priteau authored Nov 18, 2009
116 * Use `version:write` and specify `BUILD=pre1`
1aecac1 @technicalpickles zomg, so much doc updates.
authored Nov 18, 2009
117 * Edit VERSION by hand to add a fourth version segment
118
119 Jeweler does not provide a `version:bump:build` because the build version can really be anything, so it's hard to know what should be the next bump.
120
121 ## Releasing
8dc038d @technicalpickles Added example for rdoc and testing.
authored Oct 12, 2008
122
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 16, 2009
123 Jeweler handles releasing your gem into the wild:
8dc038d @technicalpickles Added example for rdoc and testing.
authored Oct 12, 2008
124
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 16, 2009
125 rake release
8dc038d @technicalpickles Added example for rdoc and testing.
authored Oct 12, 2008
126
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 16, 2009
127 It does the following for you:
8dc038d @technicalpickles Added example for rdoc and testing.
authored Oct 12, 2008
128
2aaf64b @technicalpickles Made README less novel-like, and more direct.
authored Jan 16, 2009
129 * Regenerate the gemspec to the latest version of your project
1aecac1 @technicalpickles zomg, so much doc updates.
authored Nov 18, 2009
130 * git pushes to origin/master branch
131 * git tags the version and pushes to the origin remote
8dc038d @technicalpickles Added example for rdoc and testing.
authored Oct 12, 2008
132
bea2b30 @priteau Fix some typos and remove trailing whitespace in README
priteau authored Nov 18, 2009
133 As is though, it doesn't actually get your gem anywhere. To do that, you'll need to use rubyforge or gemcutter.
1aecac1 @technicalpickles zomg, so much doc updates.
authored Nov 18, 2009
134
135 ### Releasing to Gemcutter
53ada0f @ddollar Added support for releasing to gemcutter [#27].
ddollar authored Aug 13, 2009
136
137 Jeweler can also handle releasing to [Gemcutter](http://gemcutter.org). There are a few steps you need to do before doing any Gemcutter releases with Jeweler:
138
139 * [Create an account on Gemcutter](http://gemcutter.org/sign_up)
b2c74ab @technicalpickles Updated gemcutter instructions.
authored Nov 4, 2009
140 * Install the Gemcutter gem: gem install gemcutter
1aecac1 @technicalpickles zomg, so much doc updates.
authored Nov 18, 2009
141 * Run 'gem tumble' to set up RubyGems to use gemcutter as the default source if you haven't already
2d5b86f @technicalpickles Updated documentation for Gemcutter and Rubyforge releasing.
authored Sep 23, 2009
142 * Update your Rakefile to make an instance of `Jeweler::GemcutterTasks`
143
144
145 A Rakefile setup for gemcutter would include something like this:
146
147 begin
148 require 'jeweler'
ee4cbea @agrimm Fixed error in method name. Made block variable names more consistent.
agrimm authored Nov 7, 2009
149 Jeweler::Tasks.new do |gemspec|
bea2b30 @priteau Fix some typos and remove trailing whitespace in README
priteau authored Nov 18, 2009
150 # omitted for brevity
2d5b86f @technicalpickles Updated documentation for Gemcutter and Rubyforge releasing.
authored Sep 23, 2009
151 end
152 Jeweler::GemcutterTasks.new
153 rescue LoadError
154 puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
155 end
156
53ada0f @ddollar Added support for releasing to gemcutter [#27].
ddollar authored Aug 13, 2009
157
bea2b30 @priteau Fix some typos and remove trailing whitespace in README
priteau authored Nov 18, 2009
158 After you have configured this, `rake release` will now also release to Gemcutter.
1aecac1 @technicalpickles zomg, so much doc updates.
authored Nov 18, 2009
159
160 If you need to release it without the rest of the release task, you can run:
53ada0f @ddollar Added support for releasing to gemcutter [#27].
ddollar authored Aug 13, 2009
161
162 $ rake gemcutter:release
163
1aecac1 @technicalpickles zomg, so much doc updates.
authored Nov 18, 2009
164 ### Releasing to RubyForge
a0ed80b @jtrupiano Add tests for poorly configured rubyforge_project. Update README to i…
jtrupiano authored Mar 7, 2009
165
3be96c6 @technicalpickles Updated documentation and changelog for rubyforge support.
authored Mar 12, 2009
166 Jeweler can also handle releasing to [RubyForge](http://rubyforge.org). There are a few steps you need to do before doing any RubyForge releases with Jeweler:
167
168 * [Create an account on RubyForge](http://rubyforge.org/account/register.php)
2d5b86f @technicalpickles Updated documentation for Gemcutter and Rubyforge releasing.
authored Sep 23, 2009
169 * Request a project on RubyForge.
3be96c6 @technicalpickles Updated documentation and changelog for rubyforge support.
authored Mar 13, 2009
170 * Install the RubyForge gem: sudo gem install rubyforge
171 * Run 'rubyforge setup' and fill in your username and password for RubyForge
172 * Run 'rubyforge config' to pull down information about your projects
173 * Run 'rubyforge login' to make sure you are able to login
2d5b86f @technicalpickles Updated documentation for Gemcutter and Rubyforge releasing.
authored Sep 23, 2009
174 * In Jeweler::Tasks, you must set `rubyforge_project` to the project you just created
175 * Add Jeweler::RubyforgeTasks to bring in the appropriate tasks.
176 * Note, using `jeweler --rubyforge` when generating the project does this for you automatically.
3be96c6 @technicalpickles Updated documentation and changelog for rubyforge support.
authored Mar 13, 2009
177
8ca2a95 @technicalpickles Trying to fix formatting of code snippets for rubyforge.
authored Sep 23, 2009
178 A Rakefile setup for rubyforge would include something like this:
179
3be96c6 @technicalpickles Updated documentation and changelog for rubyforge support.
authored Mar 13, 2009
180 begin
181 require 'jeweler'
ee4cbea @agrimm Fixed error in method name. Made block variable names more consistent.
agrimm authored Nov 7, 2009
182 Jeweler::Tasks.new do |gemspec|
2d5b86f @technicalpickles Updated documentation for Gemcutter and Rubyforge releasing.
authored Sep 23, 2009
183 # ommitted for brevity
ee4cbea @agrimm Fixed error in method name. Made block variable names more consistent.
agrimm authored Nov 7, 2009
184 gemspec.rubyforge_project = 'the-perfect-gem' # This line would be new
3be96c6 @technicalpickles Updated documentation and changelog for rubyforge support.
authored Mar 13, 2009
185 end
186
2d5b86f @technicalpickles Updated documentation for Gemcutter and Rubyforge releasing.
authored Sep 23, 2009
187 Jeweler::RubyforgeTasks.new do |rubyforge|
188 rubyforge.doc_task = "rdoc"
5bf5761 @technicalpickles Updated README, and updated rakefile for rubyforge.
authored Mar 26, 2009
189 end
190 rescue LoadError
2d5b86f @technicalpickles Updated documentation for Gemcutter and Rubyforge releasing.
authored Sep 23, 2009
191 puts "Jeweler, or a dependency, not available. Install it with: sudo gem install jeweler"
5bf5761 @technicalpickles Updated README, and updated rakefile for rubyforge.
authored Mar 26, 2009
192 end
193
2d5b86f @technicalpickles Updated documentation for Gemcutter and Rubyforge releasing.
authored Sep 23, 2009
194 Now you must initially create a 'package' for your gem in your RubyForge 'project':
3be96c6 @technicalpickles Updated documentation and changelog for rubyforge support.
authored Mar 13, 2009
195
196 $ rake rubyforge:setup
197
bea2b30 @priteau Fix some typos and remove trailing whitespace in README
priteau authored Nov 18, 2009
198 After you have configured this, `rake release` will now also release to RubyForge.
1aecac1 @technicalpickles zomg, so much doc updates.
authored Nov 18, 2009
199
200 If you need to release it without the rest of the release task, you can run:
3be96c6 @technicalpickles Updated documentation and changelog for rubyforge support.
authored Mar 13, 2009
201
202 $ rake rubyforge:release
a0ed80b @jtrupiano Add tests for poorly configured rubyforge_project. Update README to i…
jtrupiano authored Mar 7, 2009
203
1aecac1 @technicalpickles zomg, so much doc updates.
authored Nov 18, 2009
204 ## Development and Release Workflow
7eba48a @technicalpickles Added note about the workflow.
authored Jan 17, 2009
205
206 * Hack, commit, hack, commit, etc, etc
207 * `rake version:bump:patch release` to do the actual version bump and release
1aecac1 @technicalpickles zomg, so much doc updates.
authored Nov 18, 2009
208 * Have a delicious beverage (I suggest scotch)
Something went wrong with that request. Please try again.