Improve README.rubygems

1 files changed, 39 insertions, 5 deletions

diff --git a/README.rubygems b/README.rubygems
index 1afb62d..d7bf2bd 100644
--- a/README.rubygems
+++ b/README.rubygems
@@ -5,6 +5,17 @@ First, beware that RubyGem .gemspec files are actually normal Ruby programs,
 and are executed when loaded. A Bundler Gemfile is also a Ruby program, and
 could run arbitrary code when loaded.
 
+Second, note that when I asked on the freenode #ruby-lang IRC channel about
+associating Gems with their upstream repos, I got the impression that in
+general Ruby developers aren't wild about the idea of people bypassing their
+Gem releases and using their code straight from version control instead.
+
+The rubygems.org site adds an extra point where code can be tampered with
+by malicious folk looking to add backdoors and the like. While there is a
+mechanism for signing Gems, I found only a few (the Net:SSH family) which
+actually made use of it. (I am of course not saying that trusting upstream
+version control systems is secure in itself, but it reduces risk).
+
 The Standard Case
 -----------------
 
@@ -12,15 +23,31 @@ Most Ruby projects provide one or more .gemspec files, which describe the
 runtime and development dependencies of the Gem.
 
 Using the .gemspec file and the `gem build` command it is possible to create
-the .gem file. It can then be installed with `gem install`.
+the .gem file. It can then be installed with `gem install`. The default
+build instructions generated by the RubyGems importer use this method.
 
 Note that use of `gem build` is discouraged by its own help file in favour
 of using Rake, but there is much less standardisation among Rakefiles and they
 may introduce requirements on Hoe, rake-compiler, Jeweler or other tools.
 
-The 'development' dependencies includes everything useful to test, document,
-and create a Gem of the project. All we want to do is create a Gem, which I'll
-refer to as 'building'.
+When looking at Gem dependencies, bear in mind that the 'development'
+dependency set usually includes everything useful to test, document, and create
+a Gem of the project. All we want to do as part of a Morph build is create and
+install a Gem file. This can often be done with no build dependencies beyond
+Ruby and Gem.
+
+
+Bundler
+-------
+
+Many projects use Bundler, which allows you to collect dependency info in
+a file named Gemfile. Most put the important dependency info in their .gemspec
+file or files, and then include the .gemspec in the Gemfile. For this reason
+the tool looks for .gemspec files directly and ignores Gemfiles.
+
+Bundler allows you to lock the exact versions of all the project's
+dependencies and write them to a file named 'Gemfile.lock'. The RubyGems
+importer will make use of this information if it is available.
 
 
 Gem with no .gemspec
@@ -30,7 +57,8 @@ Some Gems choose not to include a .gemspec, like [Nokigori]. In the case of
 Nokigori, and others, [Hoe] is used, which adds Rake tasks that create the Gem.
 The `gem build` command cannot not be used in these cases.
 
-You may be able to use the `rake gem` command instead of `gem build`.
+You can often use the `rake gem` command instead of `gem build` in these cases.
+The generated .gem will be in a subdirectory named 'pkg/'.
 
 [Nokigori]: https://github.com/sparklemotion/nokogiri/blob/master/Y_U_NO_GEMSPEC.md
 [Hoe]: http://www.zenspider.com/projects/hoe.html
@@ -50,3 +78,9 @@ to be shared except as part of the build system. The .gemspec may include a
 their private key. Removing this field causes an unsigned Gem to be built.
 
 Known Gems that do this: 'net-ssh' and family.
+
+
+setup.rb
+--------
+
+The setup.rb program is rather outdated and you should try to avoid using it.