dev/pkg/spf-2.0: Document common needed changes.

1 files changed, 63 insertions, 0 deletions

diff --git a/dev/pkg/spf-2.0.mdwn b/dev/pkg/spf-2.0.mdwn
index 8935d4b..d3a748a 100644
--- a/dev/pkg/spf-2.0.mdwn
+++ b/dev/pkg/spf-2.0.mdwn
@@ -13,6 +13,10 @@ updated to SPF 2.0 and opkhelper 3.0 to be released with ProteanOS 1.0.
 [spf-1.0]: http://specs.proteanos.com/source-package-format-1.0.html
 [spf-2.0]: http://specs.proteanos.com/spf-2.0/
 
+
+Packages
+========
+
 The following packages currently need to be upgraded:
 
 Unclaimed Packages
@@ -48,3 +52,62 @@ Finished Packages
   * `fakeroot`
   * `gcc-defaults`
   * `zlib`
+
+
+Changes Necessary
+=================
+
+See the SPF 2.0 specification for [a list of changes][spf-changes] introduced
+since SPF 1.0.
+
+These are the most common changes to update packages to SPF 2.0:
+
+  * Remove the old `Source` and `Version` [source package fields][spf-fields-s].
+  * Remove the old `Package` [binary package field][spf-fields-b].
+  * Add a `Platform` [binary package field][spf-fields-b] (usually with the
+    value "`all`".
+  * Rewrite [`build` makefiles][spf-build] to use the new `build` and `install`
+    targets.
+
+See the manual pages for opkhelper 3.0 utilities to learn more about their
+options.
+
+These are the most common changes to update packages to opkhelper 3.0 and to use
+multiarch library directories:
+
+  * Remove calls to obsolete opkhelper 1.0 utilities, e.g. `oh-installdocs`,
+    `oh-gencontrol`, and `oh-buildopk`.
+  * Update arguments given to opkhelper utilities.  `oh-installfiles` no longer
+    needs a list of packages, and `oh-strip` no longer needs a list of files.
+  * Use new `oh-auto*` build system utilities.
+  * Change commands like "`rm -f /usr/lib/lib….la`" to
+    "`rm -f /usr/lib/*/lib….la`".
+  * Rename `<binpkg>.pkg/install` to `<binpkg>.pkg/files`.
+  * Change "`/usr/lib/lib….so…`" patterns to "`/usr/lib/*/lib….so…`" in
+    `<binpkg>.pkg/files`.
+  * Add "`opkhelper-3.0`" to `Build-Depends`.
+
+Finally, add a [`changelog` entry][spf-changelog] documenting the changes.  Be
+sure to add "`trunk`" (the distribution) to the end of the first line of the new
+entry.  Also make sure the version identifier is [properly formed][spf-ver].
+Following is an example changelog entry (from [zlib][zlib-changelog]):
+
+    zlib (1.2.7+sip1-1) trunk
+    
+     * New upstream version.
+     * Update to SPF 2.0 and opkhelper 3.0.
+     * Use multiarch library directories.
+     * Don't distribute IETF RFCs (SIP compliance).
+    
+     -- "P. J. McDermott" <pjm@nac.net> Wed, 03 Apr 2013 15:06:09 -0400
+
+See [this commit][zlib-update] for an example of the changes.
+
+[spf-changes]: http://specs.proteanos.com/spf-2.0/about.html#changes
+[spf-fields-s]: http://specs.proteanos.com/spf-2.0/fields.html#fields-src
+[spf-fields-b]: http://specs.proteanos.com/spf-2.0/fields.html#fields-bin
+[spf-build]: http://specs.proteanos.com/spf-2.0/buildsys.html#build
+[spf-changelog]: http://specs.proteanos.com/spf-2.0/metadata.html#changelog
+[spf-ver]: http://specs.proteanos.com/spf-2.0/metadata.html#src-ver
+[zlib-changelog]: http://git.proteanos.com/pkg/zlib.git/tree/changelog?id=03828eb2
+[zlib-update]: http://git.proteanos.com/pkg/zlib.git/commit/?id=791200f2