From 06d19e3f2fc16d374630f9d1ed0a5c64d95da11b Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Mon, 9 Oct 2023 14:48:00 +0200
Subject: Add another section to packaging guide

---
 doc/packaging.cli | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

(limited to 'doc/packaging.cli')

diff --git a/doc/packaging.cli b/doc/packaging.cli
index db98c1d..356cfc4 100644
--- a/doc/packaging.cli
+++ b/doc/packaging.cli
@@ -100,6 +100,78 @@ normally be possible to move/rename the top-level \c{tests/} directory or to
 place the library source directory into a subdirectory.
 
 
+\h#dont-forget-update-manifest|Don't forget to update \c{manifest} values|
+
+After \l{#dont-from-scratch generating the project template with \c{bdep-new}},
+don't forget to update at least the key values in the generated \c{manifest}:
+\c{version}, \c{license}, and \c{summary}.
+
+For \c{version}, use the upstream version directly if it is semver (or
+semver-like, that is, has three version components). Otherwise, see
+\l{https://github.com/build2/HOWTO/blob/master/entries/handle-projects-which-dont-use-semver.md
+How do I handle projects that don't use semantic versioning?} and
+\l{https://github.com/build2/HOWTO/blob/master/entries/handle-projects-which-dont-use-version.md
+How do I handle projects that don't use versions at all?}
+
+For \c{license}, use the \l{https://spdx.org/licenses/ SPDX license ID} if at
+all possible. If multiple licenses are involved, use the SPDX License
+expression. See the
+\l{https://build2.org/bpkg/doc/build2-package-manager-manual.xhtml#manifest-package-license
+\c{license} manifest value} documentation for details and the list of the
+most commonly used SPDX license IDs.
+
+For \c{summary} use a brief description of the functionality provided by the
+package. Less than 70 characters is a good target to aim for. Don't capitalize
+subsequent words unless proper nouns and omit the trailing dot. For example:
+
+\
+summary: Vim xxd hexdump utility
+\
+
+Omit weasel words such as \"modern\", \"simple\", \"fast\", \"small\", etc.,
+since they don't convey anything specific. Omit \"header-only\" or
+\"single-header\" for C/C++ libraries since at least in the context of
+\c{build2} it does not imply any advantage.
+
+If upstream does not offer a sensible summary, the following template is
+recommended for libraries:
+
+\
+summary: <functionality> C library
+summary: <functionality> C++ library
+\
+
+For example:
+
+\
+summary: Event notification C library
+summary: Validating XML parsing and serialization C++ library
+\
+
+If the project consists of multiple packages it may be tempting to name each
+package in terms of the overall project name, for example:
+
+\
+summary: libigl's core module
+\
+
+This doesn't give the user any clue about what functionality is provided
+unless they find out what \c{libigl} is about. Better:
+
+\
+summary: Geometry processing C++ library, core module
+\
+
+If you follow the above pattern, then to produce a summary for external tests
+or examples packages simply add \"tests\" or \"examples\" at the end,
+for example:
+
+\
+summary: Event notification C library tests
+summary: Geometry processing C++ library, core module examples
+\
+
+
 \h#dont-header-only|Don't make a library header-only if it can be compiled|
 
 Some libraries offer two alternative modes: header-only and compiled. Unless
-- 
cgit v1.1