Skip to content
Browse files

Add publishing guide

  • Loading branch information...
1 parent 49591d7 commit 8b43691839e7cb646623ddc672c8d23b62d3d310 @ffmike ffmike committed Feb 3, 2013
Showing with 105 additions and 2 deletions.
  1. +5 −0 index.md
  2. +1 −1 make-your-own-gem.md
  3. +1 −1 patterns.md
  4. +98 −0 publishing.md
View
5 index.md
@@ -12,6 +12,11 @@ Unpack the mystery behind what's in a RubyGem.
Start with an idea, end with a distributable package of Ruby code.
+[Publishing your gem](/publishing)
+---------------
+
+Start with an idea, end with a distributable package of Ruby code.
+
[Patterns](/patterns)
---------------
View
2 make-your-own-gem.md
@@ -2,7 +2,7 @@
layout: default
title: Make your own gem
previous: /what-is-a-gem
-next: /patterns
+next: /publishing
---
From start to finish, learn how to package your Ruby code in a gem.
View
2 patterns.md
@@ -1,7 +1,7 @@
---
layout: default
title: Patterns
-previous: /make-your-own-gem
+previous: /publishing
next: /specification-reference
---
View
98 publishing.md
@@ -0,0 +1,98 @@
+---
+layout: default
+title: Publishing your gem
+previous: /make-your-own-gem
+next: /patterns
+---
+
+Ways to share your gem code with other users.
+
+* [Introduction](#intro)
+* [Sharing Source Code](#sharing-source)
+* [Serving Your Own Gems](#serving)
+* [Publishing to RubyGems.org](#rubygems-org)
+* [Gem Security](#gem-security)
+
+<a id="intro"> </a>
+Introduction
+------------
+
+Now that you've [created your gem](/make-your-own-gem), you're probably ready to share it.
+While it is perfectly reasonable to create private gems solely to organize the code in large
+private projects, it's more common to build gems so that they can be used by multiple projects.
+This guide discusses the various ways that you can share your gem with the world.
+
+<a id="sharing-source"> </a>
+Sharing Source Code
+-------------------
+
+The simplest way (from the author's perspective) to share a gem for other developers' use is to
+distribute it in source code form. If you place the full source code for your gem on a public
+git repository (often, though not always, this means sharing it via [GitHub](https://github.com)),
+then other users can install it with [Bundler's git functionality](http://gembundler.com/git.html).
+
+For example, you can install the latest code for the wicked_pdf gem in a project by including this
+line in your Gemfile:
+
+ gem "wicked_pdf", :git => "git://github.com/mileszs/wicked_pdf.git"
+
+> Installing a gem directly from a git repository is a feature of Bundler, not a feature
+> of RubyGems. Gems installed this way will not show up when you run `gem list`.
+
+<a id="serving"> </a>
+Serving Your Own Gems
+---------------------
+
+If you want to control who can install a gem, or directly track the activity surrounding a gem, then
+you'll want to set up a private gem server. You can [set up your own gem server](/run-your-own-gem-server) or
+use a commercial service such as [Gemfury](http://www.gemfury.com/).
+
+See the [Resources](/resources) guide for an up-to-date listing of options for private gem servers.
+
+<a id="rubygems-org"> </a>
+Publishing to RubyGems.org
+--------------------------
+
+The simplest way to distribute a gem for public consumption is to use [RubyGems.org](https://rubygems.org/).
+Gems that are published to RubyGems.org can be installed via the `gem install` command or through the use
+of tools such as Isolate or Bundler.
+
+To begin, you'll need to create an account on RubyGems.org. Visit the [sign up](https://rubygems.org/users/new)
+page and supply an email address that you control, a handle (username) and a password.
+
+After creating the account, use the handle and password you supplied to retrieve your API key from the
+RubyGems.org server. For example, if your handle is 'squidbot':
+
+ $ curl -u squidbot https://rubygems.org/api/v1/api_key.yaml > ~/.gem/credentials
+ Enter host password for user 'squidbot':
+
+This will retrieve your API key and save it to your `~/.gem/credentials` file. Installing this key file is
+what allows the gem push command to work, associating any pushed gems with your RubyGems.org account. To
+publish version 0.1.0 of a new gem named 'squid-utils':
+
+ $ gem push squid-utils-0.1.0.gem
+ Pushing gem to RubyGems.org...
+ Successfully registered gem: squid-utils (0.1.0)
+
+Congratulations! Your new gem is now ready for any ruby user in the world to install!
+
+<a id="gem-security"> </a>
+Gem Security
+------------
+
+Installing a gem allows that gem's code to run in the context of your application. Clearly this has
+security implications: installing a malicious gem on a server could ultimately result in that
+server being completely penetrated by the gem's author. Because of this, the security of gem
+code is a topic of active discussion within the Ruby community.
+
+RubyGems has had the ability to [cryptographically sign gems](http://docs.rubygems.org/read/chapter/21)
+since version 0.8.11. This signing works by using the `gem cert` command to create a key pair, and then
+packaging signing data inside the gem itself. The `gem install` command optionally lets you set a
+security policy, and you can verify the signing key for a gem before you install it.
+
+However, this method of securing gems is not widely used. It requires a number of manual steps on the
+part of the developer, and there is no well-established chain of trust for gem signing keys. Discussion
+of new signing models using X509 or OpenPGP is going on in the
+[rubygems-trust wiki](https://github.com/rubygems-trust/rubygems.org/wiki/_pages) and
+in [IRC](irc://chat.freenode.net/#rubygems-trust). The goal is to improve (or replace) the signing
+system so that it is easy for authors and transparent for users.

0 comments on commit 8b43691

Please sign in to comment.
Something went wrong with that request. Please try again.