Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 143 lines (110 sloc) 5.12 kb
cd905b8 @qrush add pages for the rest
qrush authored
1 ---
2 layout: default
3 title: Patterns
4 previous: /make-your-own-gem
5 next: /command-reference
6 ---
7
8 Patterns
9 ========
10
11 Common practices to make your gem users and other developers' lives easier.
ab5b273 @qrush stop some errors, make h3's not look stupid, start on patterns
qrush authored
12
13 * [Consistent naming](#consistent-naming)
14 * [Semantic versioning](#semantic-versioning)
15 * [Declaring dependencies](#declaring-dependencies)
16 * [Loading code](#loading-code)
17 * [Other files](#other-files)
18 * [Requiring 'rubygems'](#requiring-rubygems)
19 * [Prerelease gems](#prerelease-gems)
20
21 <a id="consistent-naming"> </a>
22 Consistent naming
23 -----------------
24
25 > There are only two hard things in Computer Science: cache invalidation and naming things.
26 > -[Phil Karlton](http://martinfowler.com/bliki/TwoHardThings.html)
27
28 ### File names
29
30 Be consistent with how your gem files in `lib` and `bin` are named. The
31 [hola](http://github.com/qrush/hola) gem from the [make your own
32 gem](/make-your-own-gem) guide is a great example:
33
34 % tree
35 .
36 ├── Rakefile
37 ├── bin
38 │   └── hola
39 ├── hola.gemspec
40 ├── lib
41 │   ├── hola
42 │   │   └── translator.rb
43 │   └── hola.rb
44 └── test
45 └── test_hola.rb
46
47 The executable and the primary file in `lib` are named the same. A developer
48 can easily jump in and call `require 'hola'` with no problems.
49
50 ### Naming your gem
51
52 Naming your gem is important. Before you pick a name for your gem, please do a
53 quick search on [RubyGems.org](http://rubygems.org) or
54 [GitHub](http://github.com/search) to see if someone else has taken it. Once
55 you have a name, we have a [few
56 guidelines](http://blog.segment7.net/2010/11/15/how-to-name-gems) on how
57 to name them, paraphrased below.
58
59 ### Use underscores for spaces
60
61 Such as [newrelic_rpm](http://rubygems.org/gems/newrelic_rpm) or
62 [factory_girl](http://rubygems.org/gems/factory_girl). This matches the file in
63 your gem that your users will `require` along with the name. For example,
64 `gem install my_gem` will match `require 'my_gem'`
65
66 ### Use dashes for extensions
67
68 Adding new functionality to an existing gem? Use a dash. Some examples include
69 [net-http-persistent](https://rubygems.org/gems/net-http-persistent) and
70 [autotest-growl](https://rubygems.org/gems/net-http-persistent).
71
72 Usually this implies that you'll have to `require` into their directory tree
73 as well. For example, `gem install net-http-persistent` becomes `require
74 'net/http/persistent'`.
75
76 ### Don't use UPPERCASE
77
78 These gems cause problems for gem users on OSX and Windows, which use
79 case-insensitive filesystems. Plus, when installing gems it's confusing. Do I
80 run `gem install Hola` or `gem install hola` ? Just keep it lowercase.
81
82 <a id="semantic-versioning"> </a>
83 Semantic versioning
84 -------------------
85
29e00c2 @qrush versioning
qrush authored
86 A versioning policy is merely a set of simple rules governing how version
87 numbers are allocated. It can be very simple (e.g. the version number is a
88 single number starting with 1 and incremented for each successive version), or
89 it can be really strange (Knuth’s[#knuth] TeX project had version numbers: 3,
90 3.1, 3.14, 3.141, 3.1415; each successive version added another digit to PI).
91
92 The RubyGems team **strongly recommends** gem developers to follow [Semantic
93 Versioning](http://semver.org) for their gem's versions. The RubyGems library itself does
94 not enforce a strict versioning policy, but using an "irrational" policy will
95 only be a disservice to those in the community who use your gems.
96
97 Let's say we have a 'stack' gem that holds a `Stack` class with both `push` and
98 `pop` functionalty. Our `CHANGELOG` with SemVer version bumping might look
99 like this:
100
101 * **Version 0.0.1**: The initial Stack class is release.
102 * **Version 0.0.2**: Switched to a linked list implementation because it is cooler.
103 * **Version 0.1.0**: Added a `depth` method.
104 * **Version 1.0.0**: Added `top` and made `pop` return nil (pop used to return the old top item).
105 * **Version 1.1.0**: `push` now returns the value pushed (it used it return nil).
106 * **Version 1.1.1**: Fixed a bug in the linked list implementation.
107 * **Version 1.1.2**: Fixed a bug introduced in the last fix.
108
109 This system can basically boil down to:
110
111 * **PATCH** `0.0.x` level changes for implementation level detail changes, such as
112 small bug fixes
113 * **MINOR** `0.x.0` level changes for any backwards compatible API changes, such as
114 new functionality/features
115 * **MAJOR** `x.0.0` level changes for backwards *incompatible* API changes, such
116 as changes that will break existing users code if they update
117
118 If you're dealing with a lot of gem dependencies in your application, we
119 recommend that you take a look into [Bundler](http://gembundler.com) or
120 [Isolate](http://github.com/jbarnette/isolate) which do a great job of
121 managing a complex version manifest for many gems.
122
ab5b273 @qrush stop some errors, make h3's not look stupid, start on patterns
qrush authored
123 <a id="declaring-dependencies"> </a>
124 Declaring dependencies
125 ----------------------
126
127 <a id="loading-code"> </a>
128 Loading code
129 ------------
130
131 <a id="other-files"> </a>
132 Other files
133 -----------
134
135 <a id="requiring-rubygems"> </a>
136 Requiring `'rubygems'`
137 --------------------
138
139 <a id="prerelease-gems"> </a>
140 Prerelease gems
141 --------------------
142
Something went wrong with that request. Please try again.