From af5ada53bbc3910eefe159bdc572b4b631df4961 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Tue, 13 Feb 2024 09:02:39 +0200
Subject: Further work on packaging guide

---
 doc/packaging.cli | 51 ++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 46 insertions(+), 5 deletions(-)

(limited to 'doc')

diff --git a/doc/packaging.cli b/doc/packaging.cli
index 450a450..7f3603e 100644
--- a/doc/packaging.cli
+++ b/doc/packaging.cli
@@ -2895,10 +2895,10 @@ smoke test with upstream tests} to add upstream examples/benchmarks and test
 the result.
 
 
-\h#core-root|Adjust root \c{buildfile} and \c{manifest}|
+\h#core-root|Adjust root \c{buildfile}, \c{manifest}, and \c{PACKAGE-README.md}|
 
 The last few files that we need to review and potentially adjust are
-the root \c{buildfile} and package \c{manifest}.
+the root \c{buildfile}, package \c{manifest}, and \c{PACKAGE-README.md}.
 
 
 \h2#core-root-buildfile|Adjust root \c{buildfile}|
@@ -3077,7 +3077,7 @@ $ bdep ci
 
 \h2#core-root-manifest|Adjust \c{manifest}|
 
-The last file we need to look over is the package's \c{manifest}. Here is what
+The next file we need to look over is the package's \c{manifest}. Here is what
 it typically looks like, using our \c{libfoo} as an example:
 
 @@ TODO: regenerate with final version.
@@ -3242,6 +3242,42 @@ $ git push
 $ bdep ci
 \
 
+\h2#core-root-package-readme|Adjust \c{PACKAGE-README.md}|
+
+The last file we need to adjust is \c{PACKAGE-README.md} which describes how
+to use the package from a \c{build2}-based project. The template generated by
+\c{bdep-new} establishes the recommended structure and includes a number of
+placeholders enclosed in \c{< >}, such as \c{<UPSTREAM-NAME>} and
+\c{<SUMMARY-OF-FUNCTIONALITY>}, that need to be replaced with package-specific
+content. While all the placeholders should be self-explanatory, below are
+a couple of guidelines.
+
+For \c{<SUMMARY-OF-FUNCTIONALITY>} it's best to copy a paragraph or two from
+the upstream documentation, usually from \c{README.md} or the project's web
+page.
+
+If the package contains a single importable target, as is typical with
+libraries, then it makes sense to drop the \"Importable targets\" section
+since it won't add anything that hasn't already been said in the \"Usage\"
+section.
+
+Similarly, if the package has no configuration variables, then it makes sense
+to drop the \"Configuration variables\" section.
+
+@@ Fix libeven, byacc/xxd PACKAGE-README.md and recomment for inspiration.
+
+Once \c{PACKAGE-README.md} is ready, commit and push the changes. You may also
+want to view the result on GitHub to make sure everything is rendered
+correctly.
+
+\
+$ cd foo/ # Change to the package repository root.
+$ git add .
+$ git status
+$ git commit -m \"Adjust PACKAGE-README.md\"
+$ git push
+\
+
 
 \h#core-release-publish|Release and publish|
 
@@ -3671,6 +3707,13 @@ similar to the \l{#core-root-buildfile Adjust root \c{buildfile}} and
 initial packaging steps.
 
 
+\h2#core-version-management-new-version-root|New version: review \c{manifest} and \c{PACKAGE-README.md}|
+
+It makes sense to review the package \c{manifest} (\l{#core-root-manifest
+Adjust \c{manifest}}) and \c{PACKAGE-README.md} (\l{#core-root-package-readme
+Adjust \c{PACKAGE-README.md}}) for any updates.
+
+
 \h2#core-version-management-new-version-issues|New version: review/fix accumulated issues|
 
 When a bug is identified in an already released package version, we may not
@@ -3750,8 +3793,6 @@ it corresponds to the \c{2.Y.Z} release series. If you already have the
 
 ========
 
-@@ Edit PACKAGE-README.md section somewhere.
-
 @@ Enforce continous versioning with pre-commit hook -- maybe add a note?
 
 @@ Add example of propagating config.libfoo.debug to macro on build options?
-- 
cgit v1.1