From ab5b27345ada71721b2637e6a310f4cbbafbf7d4 Mon Sep 17 00:00:00 2001
From: Nick Quaranto <nick@quaran.to>
Date: Sat, 30 Apr 2011 16:43:42 -0400
Subject: [PATCH] stop some errors, make h3's not look stupid, start on
 patterns

---
 make-your-own-gem.md    |  2 +-
 patterns.md             | 94 +++++++++++++++++++++++++++++++++++++++++
 resources.md            |  2 +-
 stylesheets/screen.css  |  2 +
 stylesheets/screen.scss |  4 ++
 5 files changed, 102 insertions(+), 2 deletions(-)

diff --git a/make-your-own-gem.md b/make-your-own-gem.md
index 0bd4571a..9ca6f310 100644
--- a/make-your-own-gem.md
+++ b/make-your-own-gem.md
@@ -393,7 +393,7 @@ It's green! Well, depending on your shell colors. For more great examples, the b
 Documenting your code
 ---------------------
 
-By default most gems use [RDoc] to generate docs. There's a lot of
+By default most gems use RDoc to generate docs. There's a lot of
 [great](http://handyrailstips.com/tips/12-documenting-your-application-or-plugin-using-rdoc) 
 [tutorials](http://docs.seattlerb.org/rdoc/RDoc/Markup.html) for learning how
 to mark up your code with RDoc. Here's a simple example:
diff --git a/patterns.md b/patterns.md
index 7a94a173..9d555adf 100644
--- a/patterns.md
+++ b/patterns.md
@@ -9,3 +9,97 @@ Patterns
 ========
 
 Common practices to make your gem users and other developers' lives easier.
+
+* [Consistent naming](#consistent-naming)
+* [Semantic versioning](#semantic-versioning)
+* [Declaring dependencies](#declaring-dependencies)
+* [Loading code](#loading-code)
+* [Other files](#other-files)
+* [Requiring 'rubygems'](#requiring-rubygems)
+* [Prerelease gems](#prerelease-gems)
+
+<a id="consistent-naming"> </a>
+Consistent naming
+-----------------
+
+> There are only two hard things in Computer Science: cache invalidation and naming things.
+> -[Phil Karlton](http://martinfowler.com/bliki/TwoHardThings.html)
+
+### File names
+
+Be consistent with how your gem files in `lib` and `bin` are named. The
+[hola](http://github.com/qrush/hola) gem from the [make your own
+gem](/make-your-own-gem) guide is a great example:
+
+    % tree
+    .
+    ├── Rakefile
+    ├── bin
+    │   └── hola
+    ├── hola.gemspec
+    ├── lib
+    │   ├── hola
+    │   │   └── translator.rb
+    │   └── hola.rb
+    └── test
+        └── test_hola.rb
+
+The executable and the primary file in `lib` are named the same. A developer
+can easily jump in and call `require 'hola'` with no problems.
+
+### Naming your gem
+
+Naming your gem is important. Before you pick a name for your gem, please do a
+quick search on [RubyGems.org](http://rubygems.org) or
+[GitHub](http://github.com/search) to see if someone else has taken it. Once
+you have a name, we have a [few
+guidelines](http://blog.segment7.net/2010/11/15/how-to-name-gems) on how
+to name them, paraphrased below.
+
+### Use underscores for spaces
+
+Such as [newrelic_rpm](http://rubygems.org/gems/newrelic_rpm) or
+[factory_girl](http://rubygems.org/gems/factory_girl). This matches the file in
+your gem that your users will `require` along with the name. For example,
+`gem install my_gem` will match `require 'my_gem'`
+
+### Use dashes for extensions
+
+Adding new functionality to an existing gem? Use a dash. Some examples include
+[net-http-persistent](https://rubygems.org/gems/net-http-persistent) and
+[autotest-growl](https://rubygems.org/gems/net-http-persistent).
+
+Usually this implies that you'll have to `require` into their directory tree
+as well. For example, `gem install net-http-persistent` becomes `require
+'net/http/persistent'`.
+
+### Don't use UPPERCASE
+
+These gems cause problems for gem users on OSX and Windows, which use
+case-insensitive filesystems. Plus, when installing gems it's confusing. Do I
+run `gem install Hola` or `gem install hola` ? Just keep it lowercase.
+
+<a id="semantic-versioning"> </a>
+Semantic versioning
+-------------------
+
+<a id="declaring-dependencies"> </a>
+Declaring dependencies
+----------------------
+
+<a id="loading-code"> </a>
+Loading code
+------------
+
+<a id="other-files"> </a>
+Other files
+-----------
+
+<a id="requiring-rubygems"> </a>
+Requiring `'rubygems'`
+--------------------
+
+<a id="prerelease-gems"> </a>
+Prerelease gems
+--------------------
+
diff --git a/resources.md b/resources.md
index 2a1faa11..a99e5be3 100644
--- a/resources.md
+++ b/resources.md
@@ -37,5 +37,5 @@ Patterns
 --------
 
 * [Gem Packaging: Best Practices](http://weblog.rubyonrails.org/2009/9/1/gem-packaging-best-practices)
-* [Gem Best Practice](http://blog.nofail.de/2010/11/gem-best-practice/)
 * [Rubygems Good Practice](http://yehudakatz.com/2009/07/24/rubygems-good-practice/)
+* [Gem Development Best Practices](http://blog.carbonfive.com/2011/01/22/gem-development-best-practices/)
diff --git a/stylesheets/screen.css b/stylesheets/screen.css
index 011dc0df..578b9507 100644
--- a/stylesheets/screen.css
+++ b/stylesheets/screen.css
@@ -689,6 +689,8 @@ body.home {
       font-weight: bold;
       margin: 25px 0;
       clear: both; }
+    #container #content h3 {
+      font-size: 16px; }
     #container #content p {
       margin: 1em 0; }
     #container #content pre {
diff --git a/stylesheets/screen.scss b/stylesheets/screen.scss
index 949c19b6..4d23740e 100644
--- a/stylesheets/screen.scss
+++ b/stylesheets/screen.scss
@@ -164,6 +164,10 @@ body.home {
       clear: both;
     }
 
+    h3 {
+      font-size: 16px;
+    }
+
     p {
       margin: 1em 0;
     }