[DRE-commits] [SCM] Debian Ruby packaging policy branch, master, updated. dfed064c7e2739744dc6ad87ba69c2c6abc92b1e

[Vincent Fourmond]

The following commit has been merged in the master branch:
commit dfed064c7e2739744dc6ad87ba69c2c6abc92b1e
Author: Vincent Fourmond <fourmond at debian.org>
Date:   Mon May 9 22:08:04 2011 +0200

    Applying modifications suggested by Lucas Nussbaum

diff --git a/ruby-policy.xml b/ruby-policy.xml
index 5a225b2..58ed431 100644
--- a/ruby-policy.xml
+++ b/ruby-policy.xml
@@ -87,7 +87,7 @@
 
     <para>
       Similarly to the other subpolicies, the aim of the Debian Ruby
-      Policy is to unify the packaging of Ruby libraries and programs
+      Policy is to unify the packaging of Ruby libraries and applications
       under a single well-defined structure that packagers and users
       alike can rely on.
     </para>
@@ -102,7 +102,7 @@
       language to coexist and to share code (in as far as it is
       technically possible).
     </para>
-      
+    
     
     <para>
       As packaging practices and Ruby-related technologies evolve over
@@ -124,10 +124,6 @@
       url="&debian-policy;">Debian Policy</ulink>.
     </para>
 
-    <para>
-      Here a descroiption of the main points
-    </para>
-    
     <sect1 id="interpreters">
       <title>Ruby interpreters</title>
       
@@ -143,8 +139,8 @@
       <para>
         By library, we mean <quote>every package that contains ruby
         code and is not a Ruby interpreter</quote>. In particular,
-        this also includes programs not necessarily meant to be used
-        as libraries. For programs additional requirements and/or
+        this also includes applications not necessarily meant to be used
+        as libraries. For applications additional requirements and/or
         relaxing of some requirements listed here apply, see next
         section.
       </para>
@@ -154,56 +150,66 @@
         <para>
           All binary packages that contains Ruby code &must; have a
           package name in the form <literal>ruby-</literal>&pkg;,
-          where &pkg; is left to the choice of the packager. However,
-          packagers &may; ignore this rule in the following cases:
+          where &pkg; &should; be the <quote>library name</quote>,
+          that is either the gem name or the argument to
+          <literal>require</literal> (or the common part in case of a
+          library providing several sub-libraries that can be used
+          independently). However, packagers &may; ignore this rule in
+          the following cases:
           <itemizedlist>
             <listitem>
               <para>
-                ruby interpreters;
+                ruby interpreters, , such as
+                <literal>ruby-1.9.1</literal> or
+                <literal>jruby</literal>;
               </para>
             </listitem>
 
             <listitem>
               <para>
-                programs;
+                applications, such as <literal>chef</literal>,
+                <literal>rails</literal> or
+                <literal>rubygems</literal>.
               </para>
             </listitem>
 
-            <listitem>
-              <para>
-                packages providing ruby code to be use specifically as
-                plugins for a given program, and that have no use
-                outside of this program.
-              </para>
-            </listitem>
           </itemizedlist>
-          The source package name &should; match the name of package
-          that holds the code.
+          The source package name &should; match the name of the main
+          binary package.
         </para>
         <para>
           In the case of software previoulsy relased with the old
           package name policy
           (<literal>lib-</literal>&pkg;<literal>-ruby</literal> and
-          versioned variants thereof), packagers &should; provide
+          versioned variants thereof), packagers &must; provide
           transition packages with the old names depending on the new
           package.
         </para>
       </sect2>
 
       <sect2>
+        <title>Section</title>
+        <para>All libraries &must; be <literal>Section:
+        ruby</literal>. This rule does not apply to applications, whose
+        section should match their use.
+        </para>
+      </sect2>
+
+      <sect2>
         <title>Supported Ruby implementations</title>
         <para>
           Packages &should; support as many different implementations
           of Ruby as is possible. Reasons why this is not done
           &should; be documented visibly, such as in the
-          <filename>README.Debian</filename> file.
+          <filename>README.Debian</filename> file or the
+          <filename>changelog.Debian</filename> file
         </para>
         <para>
           Packages &must; list the versions of Ruby supported in the
           source package using the <literal>XS-Ruby-Versions</literal>
           statement in <filename>debian/control</filename>. This
           statement &must; be a space-separated list of one or more of
-          <literal>ruby1.8</literal>, <literal>ruby1.9</literal> or
+          <literal>ruby1.8</literal>, <literal>ruby1.9.1</literal> or
           <literal>all</literal> (the latter meaning all the supported
           Ruby versions).
         </para>
@@ -253,19 +259,22 @@
       <sect2>
         <title>Rubygems</title>
         <para>
-          Do we disallow the use of <literal>require
-          'rubygems'</literal> by policy ?
+          To avoid hard-to-detect mixes of Debian and local ruby
+          libraries, packages &mustnot; use
+          <literal>rubygems</literal>. In particular the use of
+          <literal>require 'rubygems'</literal> and
+          <literal>require_gem</literal> is not allowed.
         </para>
       </sect2>
       
     </sect1>
     
-    <sect1 id="programs">
-      <title>Ruby programs</title>
+    <sect1 id="applications">
+      <title>Ruby applications</title>
 
       <para>
         Excepted for the package name, which does not have to comply
-        to any rules, Ruby programs &must; obey all rules that apply
+        to any rules, Ruby applications &must; obey all rules that apply
         to Ruby libraries (previous sections).  In addition, they must
         obey the following rules.
       </para>
@@ -273,7 +282,7 @@
       <sect2>
         <title>Handling the different Ruby interpreters</title>
         <para>
-          If the program is supposed to work correcly with any Ruby
+          If the application is supposed to work correcly with any Ruby
           interpreter, than it &must; have a <literal>#!/usr/bin/ruby</literal>
           shebang, and &must; depend on
           <literal>ruby |ruby-interpreter</literal>.
@@ -281,11 +290,11 @@
           the transition to new default versions of the Ruby interpreter.
         </para>
         <para>
-          If the program is supposed to work with a specific Ruby interpreter,
+          If the application is supposed to work with a specific Ruby interpreter,
           then it &must; have a
           <literal>#!/usr/bin/rubyX.Y</literal>
           shebang and &must; depend on the specific package for that
-          interpreter. For example, a program that only works with Ruby 1.9.1
+          interpreter. For example, an application that only works with Ruby 1.9.1
           would have a <literal>#!/usr/bin/ruby1.9.1</literal> shebang and
           depend on <literal>ruby1.9.1</literal>.
         </para>
@@ -294,7 +303,7 @@
     
 
   </chapter>
-   
+  
   <chapter id="advices">
     <title>Advices to Ruby packagers</title>
     
@@ -313,3 +322,8 @@
   
 </book>
 <!-- vim: expandtab sw=2 ts=2 -->
+<!-- 
+     Local Variables:
+     indent-tabs-mode: nil
+     End:
+-->
\ No newline at end of file

-- 
Debian Ruby packaging policy