pkgsrc/doc/guide/files/fixes.xml: 1.54 -> 1.55

[kano@na.rim.or.jp (OKANO Takayoshi)]

以下のページの更新をしました。ツッコミをお願いします。

pkgsrc/doc/guide/files/fixes.xml: 1.54 -> 1.55

> revision 1.55
> date: 2006/06/14 21:20:16;  author: darcy;  state: Exp;  lines: +28 -1
> Add text to help explain when bumping PKGREVISION is appropriate or not.
> 
> As discussed with Greg Troxel.

火曜日までに異議がなければ、 commit します。

# というか、こういう programlisting の使い方はありなんでしょーか

以下、訳と原文それぞれの新旧の差分です。

--- fixes.xml.orig	2006-11-27 23:12:28.000000000 +0900
+++ fixes.xml	2006-11-27 23:12:28.000000000 +0900
@@ -1,6 +1,6 @@
-<!-- $NetBSD: fixes.xml,v 1.54 2006/06/01 09:31:18 rillig Exp $ -->
+<!-- $NetBSD: fixes.xml,v 1.55 2006/06/14 21:20:16 darcy Exp $ -->
 <!-- Based on english version: -->
-<!-- NetBSD: fixes.xml,v 1.54 2006/06/01 09:31:18 rillig Exp   -->
+<!-- NetBSD: fixes.xml,v 1.55 2006/06/14 21:20:16 darcy Exp   -->
 
 <chapter id="fixes"> <?dbhtml filename="fixes.html"?>
   <title>パッケージを動くようにする</title>
@@ -399,6 +399,33 @@
 <programlisting>
     DISTNAME=       foo-17.43
 </programlisting>
+
+    <para>バイナリーパッケージに対して自明でない変化をおよぼす場合は、すべて、
+    PKGREVISION を上げるようにします。PKGREVISION を上げないと、
+    変更前のバージョンをインストールしている人が、
+    そのパッケージが古くなったことを知るすべがなくなってしまいます。
+    したがって、PKGREVISION を上げない変更とは、本質的に
+    「誰もアップグレードする必要のない自明な変更」ということであり、
+    これが PKGREVISION を上げるべきか否かを大雑把に判断する方法です。
+    PKGREVISION を上げる意味のない変更には、たとえば以下のようなものがあります。</para>
+
+<programlisting>
+HOMEPAGE, MAINTAINER や、Makefile 中のコメントの変更。
+構築変数の変更で、作成されるバイナリーパッケージに変化がない場合。
+DESCR の変更。
+PKG_OPTIONS の追加で、標準のオプションに変化がない場合。
+</programlisting>
+
+    <para>PKGREVISION を上げる価値のある変更には、
+    たとえば以下のようなものがあります。</para>
+<programlisting>
+セキュリティーの修正
+パッチファイルの変更または追加
+PLIST の変更
+</programlisting>
+
+    <para>依存するパッケージの ABI が変更された場合にも、
+    PKGREVISION を上げる必要があります。</para>
     </sect2>
 
 
Index: fixes.xml
===================================================================
RCS file: /cvsroot/pkgsrc/doc/guide/files/fixes.xml,v
retrieving revision 1.54
retrieving revision 1.55
diff -u -r1.54 -r1.55
--- fixes.xml	1 Jun 2006 09:31:18 -0000	1.54
+++ fixes.xml	14 Jun 2006 21:20:16 -0000	1.55
@@ -1,4 +1,4 @@
-<!-- $NetBSD: fixes.xml,v 1.54 2006/06/01 09:31:18 rillig Exp $ -->
+<!-- $NetBSD: fixes.xml,v 1.55 2006/06/14 21:20:16 darcy Exp $ -->
 
 <chapter id="fixes"> <?dbhtml filename="fixes.html"?>
   <title>Making your package work</title>
@@ -432,6 +432,33 @@
 <programlisting>
     DISTNAME=       foo-17.43
 </programlisting>
+
+    <para>PKGREVISION should be incremented for any non-trivial change in the
+    resulting binary package.  Without a PKGREVISION bump, someone with
+    the previous version installed has no way of knowing that their
+    package is out of date.  Thus, changes without increasing PKGREVISION
+    are essentially labeled "this is so trivial that no reasonable person
+    would want to upgrade", and this is the rough test for when increasing
+    PKGREVISION is appropriate.  Examples of changes that do not merit
+    increasing PKGREVISION are:</para>
+
+<programlisting>
+Changing HOMEPAGE, MAINTAINER, or comments in Makefile.
+Changing build variables if the resulting binary package is the same.
+Changing DESCR.
+Adding PKG_OPTIONS if the default options don't change.
+</programlisting>
+
+    <para>Examples of changes that do merit an increase to PKGREVISION
+    include:</para>
+<programlisting>
+Security fixes
+Changes or additions to a patch file
+Changes to the PLIST
+</programlisting>
+
+    <para>PKGREVISION must also be incremented when dependencies have ABI
+    changes.</para>
     </sect2>