aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2024-02-13 09:02:39 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2024-02-13 09:02:39 +0200
commitaf5ada53bbc3910eefe159bdc572b4b631df4961 (patch)
tree1ee5dabadfd574a5afc4b43b14991db452149c4d
parent6bc7657d053d6832bb3e0ef7693b87b3ae6cfcf1 (diff)
Further work on packaging guide
-rw-r--r--doc/packaging.cli51
1 files changed, 46 insertions, 5 deletions
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?