[DRE-commits] r3266 - website/src

lucas at alioth.debian.org lucas at alioth.debian.org
Mon Mar 9 15:06:30 UTC 2009 

Author: lucas
Date: 2009-03-09 15:06:30 +0000 (Mon, 09 Mar 2009)
New Revision: 3266

Modified:
   website/src/40.rubygems.en.page
   website/src/50.upstream-devs.en.page
Log:
update rubygems and upstream devs pages

Modified: website/src/40.rubygems.en.page
===================================================================
--- website/src/40.rubygems.en.page	2009-03-09 14:44:48 UTC (rev 3265)
+++ website/src/40.rubygems.en.page	2009-03-09 15:06:30 UTC (rev 3266)
@@ -1,142 +1,59 @@
 ---
-title: Position on RubyGems
+title: On RubyGems
 inMenu: true
 ---
-h1. Common Position on RubyGems
+h1. Position on RubyGems
 
-h2. RubyGems
+The Debian pkg-ruby-extras team takes care of the packaging of third-party
+libraries (not shipped in the standard library). We describe here our position
+on RubyGems.
 
-"RubyGems":http://docs.rubygems.org/ is a packaging system for Ruby
-applications and libraries (similar to CPAN for Perl). It is widely used inside
-the Ruby community (especially inside the "Ruby on
-Rails":http://www.rubyonrails.org/ community), and solves lots of issue
-regarding packaging and distribution of Ruby software on operating systems that don't provide a package manager.  Rubygems will be
-included in Ruby's standard library in Ruby 1.9.1, and chances are high that it
-will become the de-facto standard for packaging and distributing Ruby libraries.
+"RubyGems":http://docs.rubygems.org/ has become the standard way to distribute
+and install Ruby libraries. It allows developers of libraries to distribute
+their work, and install the latest version of other libraries in an
+easy-to-install and cross-platform way, without intermediaries (like Linux
+distributions' packaging systems). RubyGems is thus clearly a very useful tool,
+from the developer point-of-view. Some other languages have similar tools, like
+"Perl's CPAN":http://www.cpan.org/, and "Python's
+eggs":http://peak.telecommunity.com/DevCenter/PythonEggs.
 
-However, the Debian/Ruby Extras team fear that Rubygems will make it much more
-difficult to package and distribute Ruby software in Debian (similar concerns
-have been raised by other individuals and GNU/Linux distributions):
+However, users (both end users of classic applications, and system
+administrators who will install web applications) have different needs. Most of
+them want their ruby applications to be installable in the same way as their
+other applications, which usually means using their Linux distribution's
+package manager. The installation of ruby applications could then use
+existing infrastructure (local proxies, for example), and security updates
+would be tracked with the same tools.
 
-* Rubygems packages are not compatible with the FHS. Rubygems follows the "one
-directory per package and version" rule.
-* It is not possible to do "normal" (FHS-compatible) installations of rubygems,
-and some ruby software developers have started to distribute their software as
-gems only.
-* Rubygems is source-intrusive. The *require* instruction is replaced by a
-*require_gem* instruction to allow for versioned dependencies. Debian and most
-other systems think that dealing with versioned dependencies outside of the
-source is a better idea.
-* There are currently no plans to improve RubyGems to ease the work of Debian
-and RPM packagers. Some RubyGems developers have also showed hostility
-towards Debian.
+Unfortunately, while other languages promote good practices that make manual
+installation and  packaging of libraries very easy (Perl's Makefile.pl,
+Python's distutils), the Ruby community tends to impose the use of RubyGems for
+everyone: it is currently impossible to install most Ruby applications
+(Rails-based applications, for example) without using RubyGems.
 
-h2. Position of the Debian/Ruby Extras Team
+We ask Ruby developers to:
 
-# We do not oppose Ruby having a packaging system. However, since Debian has
-its own system already, we feel that it is important that Debian users can
-install all software using the same tools, and that all software installed
-that way follows the same policies.
-# Since we have to follow the FHS, the current RubyGems way of installing the
-gem's contents in one directory is incompatible with our setup (and toolchain)
-and thus cannot be used.
-# For the moment we will continue to package Ruby applications and libraries as
-Debian packages from (preferably pristine) upstream sources as it always has
-been done (using *setup.rb* or *install.rb* for example). Users could then
-continue to install their apps the way they are used to (using apt-get), since
-most of them do not care about the language their apps are written in or about
-other ways this application/library is made available.
-# For Ruby developers requiring bleeding edge library versions or libraries
-that haven't been packaged (yet), a *rubygems* package will be made
-available. This package provides the gem command to be able to install/remove
-gems at the developer's own discretion and risk. The gems will be installed
-using the normal gem installation procedure, in /usr/lib/ruby/gems.
-# No package in Debian shall use the gem command during package installation
-or build.
-# No package in Debian should require that the user install software as gems.
-This would make it impossible to support (security-wise and quality-wise) such
-software.
-# Other utilities are written to couple the packaging process to the RubyGem
-system, i.e. utilities to help convert a gem to a Debian source package.
-These utilites would not solve any problems, just ease the initial
-(re)packaging work a bit. 
+* continue to provide RubyGems for their software, as they are useful for other
+Ruby developers who need latest versions of their software.
 
-h2. For Reference: file system layout of the rmail package
+* also provide their software in a format suitable for manual installation and
+packaging. For more information on specific problems we encounter with Ruby software, and how to solve them, please see "this page":upstream-devs.html
 
-h3. Content of /usr/lib/ruby/gems added after the execution of **gem install rmail**
+h2. RubyGems package in Debian
 
-<code><pre>/usr/lib/ruby
-/usr/lib/ruby/gems/
-/usr/lib/ruby/gems/1.8
-/usr/lib/ruby/gems/1.8/cache
-/usr/lib/ruby/gems/1.8/cache/rmail-0.17.gem
-/usr/lib/ruby/gems/1.8/doc
-/usr/lib/ruby/gems/1.8/doc/rmail-0.17
-/usr/lib/ruby/gems/1.8/doc/rmail-0.17/rdoc
-/usr/lib/ruby/gems/1.8/doc/rmail-0.17/rdoc/created.rid
-/usr/lib/ruby/gems/1.8/doc/rmail-0.17/rdoc/rdoc-style.css
-/usr/lib/ruby/gems/1.8/doc/rmail-0.17/rdoc/files
-/usr/lib/ruby/gems/1.8/doc/rmail-0.17/rdoc/files/lib
-/usr/lib/ruby/gems/1.8/doc/rmail-0.17/rdoc/files/lib/rmail_rb.html</pre></code>
+A "rubygems package":http://packages.debian.org/sid/rubygems is provided in
+Debian. It is aimed at developers willing to install bleeding edge library
+versions, or libraries that have not yet been packaged in Debian.  This package
+provides the gem command to be able to install/remove gems at the developer's
+own discretion and risk. The gems will be installed using the normal gem
+installation procedure, under /var/lib/gems, as the normal Gem installation
+path is incompatible with the "FHS":http://www.pathname.com/fhs/.
 
-[ ... this directory contains all the rdoc documentation provided by the librmail-ruby-doc on Debian ]
+This package must not be used to create or build Debian packages.
 
-<code><pre>/usr/lib/ruby/gems/1.8/gems/rmail-0.17
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/NEWS
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/TODO
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/NOTES
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/README
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/THANKS
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/install.rb
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/rmail.gemspec
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/lib/rmail.rb
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/lib/rmail/parser.rb
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/lib/rmail/message.rb
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/lib/rmail/header.rb
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/lib/rmail/address.rb
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/lib/rmail/mailbox.rb
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/lib/rmail/serialize.rb
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/lib/rmail/utils.rb
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/lib/rmail/mailbox/mboxreader.rb
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/lib/rmail/parser/multipart.rb
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/lib/rmail/parser/pushbackreader.rb
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/guide/MIME.txt
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/guide/TableOfContents.txt
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/guide/Intro.txt
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/tests/addrgrammar.txt
-/usr/lib/ruby/gems/1.8/gems/rmail-0.17/tests/testmboxreader.rb</pre></code>
+h2. Contact information
 
-[ ... this directory contains all rmail's unit tests, which are packaged as examples in librmail-ruby-doc in Debian ]
-
-<code><pre>/usr/lib/ruby/gems/1.8/specifications/rmail-0.17.gemspec
-/usr/lib/ruby/gems/1.8/source_cache</pre></code>
-
-h3. Files in the Debian package librmail-ruby1.8
-
-<code><pre>/usr/lib/ruby/1.8/rmail.rb
-/usr/lib/ruby/1.8/rmail/parser.rb
-/usr/lib/ruby/1.8/rmail/message.rb
-/usr/lib/ruby/1.8/rmail/header.rb
-/usr/lib/ruby/1.8/rmail/address.rb
-/usr/lib/ruby/1.8/rmail/mailbox.rb
-/usr/lib/ruby/1.8/rmail/serialize.rb
-/usr/lib/ruby/1.8/rmail/utils.rb
-/usr/lib/ruby/1.8/rmail/mailbox/mboxreader.rb
-/usr/lib/ruby/1.8/rmail/parser/multipart.rb
-/usr/lib/ruby/1.8/rmail/parser/pushbackreader.rb
-/usr/share/doc/librmail-ruby1.8/NOTES
-/usr/share/doc/librmail-ruby1.8/README
-/usr/share/doc/librmail-ruby1.8/THANKS
-/usr/share/doc/librmail-ruby1.8/TODO
-/usr/share/doc/librmail-ruby1.8/copyright
-/usr/share/doc/librmail-ruby1.8/NEWS.gz
-/usr/share/doc/librmail-ruby1.8/changelog.Debian.gz</pre></code>
-
-h2. @rubygems@ package
-
-The @rubygems@ package Daigo Moriwaki created has now reached the
-debian archive. Gems are stored in the
-@/var/lib/gem/@_rubyversion_ directory, as this is the only way to comply
-to the "FHS":http://www.pathname.com/fhs/. 
-
-
+The Debian pkg-ruby-extras team can be contacted at
+ at pkg-ruby-extras-maintainers AT lists.alioth.debian.org at .  In particular, feel
+free to send comments or questions about this document, or suggest Ruby
+libraries that we should package in Debian.

Modified: website/src/50.upstream-devs.en.page
===================================================================
--- website/src/50.upstream-devs.en.page	2009-03-09 14:44:48 UTC (rev 3265)
+++ website/src/50.upstream-devs.en.page	2009-03-09 15:06:30 UTC (rev 3266)
@@ -11,24 +11,49 @@
 from it.  However, it would be great if you could make our work as easy as
 possible by following those guidelines.
 
-h3. Don't distribute only as a gem.
+h3. Distribute your software as a source code archive
 
-"RubyGems":http://docs.rubygems.org/ is nice for people who aren't using
-another packaging system, but it makes it hard to package your application
-for our distribution.  Please distribute your software as a *.tgz* (or
-*.tar.gz*) too.
+"RubyGems":http://docs.rubygems.org/ is a useful tool for developers, but isn't a good tool for the general distribution of your software (see "this page":rubygems.html for more information).
 
-h3. Don't depend on RubyGems
+Distribute your software as a @.tar.gz@ archive. @.tar.gz@ is the most widely
+used archive format on Linux. Using other formats (@.tar.bz2@, for example) is
+discouraged, as it requires additional steps for the packager. A @.zip@ file
+could be provided for Windows users.
 
-Make sure you are using <code>require</code>, not <code>require_gem</code>,
-to allow users to use your library without using RubyGems.
+Including the version of the software in the name of the archive is also a very good idea.
 
-h3. Use setup.rb
+h3. Use @setup.rb@
 
-_TODO:_ explain differences between
-"setup.rb":http://i.loveruby.net/en/projects/setup/, extconf.rb, and
-install.rb.
+Provide a "setup.rb":http://i.loveruby.net/en/projects/setup/. Use it with its
+default layout (@bin/@, @lib/@, ...). Test that your software works when
+installed using it.
 
+If your library is only a native library, using @extconf.rb@ might be a suitable alternative. However, all extconf use-cases are covered by @setup.rb at .
+
+ at install.rb@ is deprecated, and should not be used.
+
+h3. Remove all references to rubygems in the software you ship
+
+One big issue we have with rubygems is that it is source-intrusive: developers add
+ at require 'rubygems'@ in their code, which:
+* fails if the user doesn't have rubygems installed
+* causes manually-installed (or installed with a package manager) libraries to be ignored after RubyGems has been loaded.
+
+Do not use:
+<code><pre>
+begin
+   require 'rubygems'
+rescue LoadError
+end
+</pre></code>
+As this will succeed on systems with rubygems installed.
+
+Instead, make the loading of rubygems conditional, using a global constant that
+you can easily disable before releasing:
+<code><pre>require 'rubygems' if DEVELOPER_MODE</pre></code>
+
+For the same reason, @require_gem@ must not be used.
+
 h3. Don't make your Rakefile depend on RubyGems
 
 If you provide a Rakefile, make sure it is usable without RubyGems
@@ -108,7 +133,7 @@
 
 h3. Make your tests and examples usable outside of your directory tree
 
-*Don't* do things like <code>require '../lib/yourpackagename'</code>. 
+*Do not* do things like <code>require '../lib/yourpackagename'</code>. 
 Instead, use the following example: 
 <code><pre>$:.unshift '../lib'
 
@@ -124,14 +149,25 @@
 
 The Ruby interpreter can be installed in different places.  Instead of
 using <code>#!/usr/bin/ruby</code> or <code>#!/usr/local/bin/ruby</code>,
-consider using <code>#!/usr/bin/env ruby</code>.
+use <code>#!/usr/bin/env ruby</code>.
 
 h3. Provide man pages for your binaries
 
 Some distributions (e.g. Debian) require all executables to have a man page. 
 It would be great if you could provide it yourself.
 
-h3. References
+h3. If possible, maintain a backward-compatible API
 
+Usually, distributions don't ship several versions of the same libraries. Libraries providing a stable API make this much easier.
+
+h2. References
+
 * "RPA-base: Good Pratices":http://rpa-base.rubyforge.org/wiki/wiki.cgi?GoodPractices
 * "RPA-base: Packaging Nitpick Checklist":http://rpa-base.rubyforge.org/wiki/wiki.cgi?PackagingNitpickChecklist
+
+h2. Contact information
+
+The Debian pkg-ruby-extras team can be contacted at
+ at pkg-ruby-extras-maintainers AT lists.alioth.debian.org at .  In particular, feel
+free to send comments or questions about this document, or suggest Ruby
+libraries that we should package in Debian.

More information about the Pkg-ruby-extras-commits mailing list