Initial import of Baserock import tool for importing foreign packaging

1 files changed, 52 insertions, 0 deletions

diff --git a/README.rubygems b/README.rubygems
new file mode 100644
index 0000000..1afb62d
--- /dev/null
+++ b/README.rubygems
@@ -0,0 +1,52 @@
+Here is some information I have learned while importing RubyGem packages into
+Baserock.
+
+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.
+
+The Standard Case
+-----------------
+
+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`.
+
+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'.
+
+
+Gem with no .gemspec
+--------------------
+
+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`.
+
+[Nokigori]: https://github.com/sparklemotion/nokogiri/blob/master/Y_U_NO_GEMSPEC.md
+[Hoe]: http://www.zenspider.com/projects/hoe.html
+
+
+Signed Gems
+-----------
+
+It's possible for a Gem maintainer to sign their Gems. See:
+
+  - <http://blog.meldium.com/home/2013/3/3/signed-rubygems-part>
+  - <http://www.ruby-doc.org/stdlib-1.9.3/libdoc/rubygems/rdoc/Gem/Security.html>
+
+When building a Gem in Baserock, signing is unnecessary because it's not going
+to be shared except as part of the build system. The .gemspec may include a
+`signing_key` field, which will be a local path on the maintainer's system to
+their private key. Removing this field causes an unsigned Gem to be built.
+
+Known Gems that do this: 'net-ssh' and family.