FEATURES-BY-VERSION: New document

2 files changed, 66 insertions, 0 deletions

diff --git a/FEATURES-BY-VERSION b/FEATURES-BY-VERSION
new file mode 100644
index 0000000..567910d
--- /dev/null
+++ b/FEATURES-BY-VERSION
@@ -0,0 +1,65 @@
+This document helps package maintainers write `Build-Depends` fields
+that ensure that the installed version of opkbuild supports features
+needed by a source package.  Read this document from top to bottom, and
+as soon as you find a criterion that applies to your source package, you
+can add the specified versioned build dependency and stop reading.
+
+Add `opkbuild (>= 4.2.2+dev)` to your `Build-Depends` if...
+
+  * Your binary packages don't list in their `Depends` fields the binary
+    package that provides source package documentation.
+  * Your ProteanOS source package version contains an epoch, e.g.
+    `1:2.0-1`.
+  * Any two or more of your binary packages would have the same name if
+    all characters except letters and numbers were removed, e.g.
+    `libc-1` and `libc++.1`.
+
+Add `opkbuild (>= 4.2.2)` to your `Build-Depends` if...
+
+  * Any of your substitution variables are used in binary package
+    dependency fields and contain dependency restrictions or newline
+    characters.  This is common for example in platform configuration
+    source packages that use `platconf-pkg-tools` which generates binary
+    package control files that get `Depends` field values from
+    substitution variables.
+
+Add `opkbuild (>= 4.2.1)` to your `Build-Depends` if...
+
+  * Your `Build-Depends` field contains newline characters.
+
+Add `opkbuild (>= 4.2.0)` to your `Build-Depends` if...
+
+  * Any of your binary packages has a `Section` field.
+
+Add `opkbuild (>= 4.1.4)` to your `Build-Depends` if...
+
+  * Your ProteanOS source package version indicates an upload of a new
+    upstream version to a non-trunk distribution (e.g. version
+    `2019a-0+rs1~1`) or an upload of a backport to a non-trunk
+    distribution (e.g. version `3.0-2+bpu1+1`).
+
+Add `opkbuild (>= 4.0.2)` to your `Build-Depends` if...
+
+  * Your ProteanOS source package upstream version contains a plus sign,
+    e.g. `1.4+git20141115.146bff1-1`.
+
+Add `opkbuild (>= 4.0.1)` to your `Build-Depends` if...
+
+  * You use binary package substitution variables files in the build
+    work area, e.g. with opkhelper's oh-shlibdeps utility.  If you use
+    oh-shlibdeps on ProteanOS, you should also add
+    `opkhelper-3.0 (>= 3.1.4)` to your `Build-Depends`.
+
+Add `opkbuild (>= 4.0.0)` to your `Build-Depends` if...
+
+  * Your upstream source archive is compressed using xz.
+
+Copyright Information
+---------------------
+
+Copyright (C) 2023  Patrick McDermott
+
+Copying and distribution of this file, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved.  This file is offered as-is,
+without any warranty.
diff --git a/Makefile.am b/Makefile.am
index f3dbfbc..f8219e4 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -67,6 +67,7 @@ helperdir = $(pkgdatadir)/helpers
 CLEANFILES =
 extra_sources =
 EXTRA_DIST = \
+	FEATURES-BY-VERSION \
 	NEWS.opkhelper \
 	TODO \
 	autogen.sh \