Further work on packaging guide (repository README)

1 files changed, 22 insertions, 4 deletions

diff --git a/doc/packaging.cli b/doc/packaging.cli
index e52217e..5f14903 100644
--- a/doc/packaging.cli
+++ b/doc/packaging.cli
@@ -3808,10 +3808,10 @@ $ 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
+The last package 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 the
 package-specific content. While all the placeholders should be
 self-explanatory, below are a couple of guidelines.
@@ -3853,6 +3853,24 @@ $ git push
 \
 
 
+\h#core-proj-readme|Adjust project \c{README.md}|
+
+With all the package files taken care of, the last file we need to adjust is
+\c{README.md} in the root of our package repository (it was created on the
+\l{#core-repo-init Initialize package repository with \c{bdep new --type
+empty}} step).
+
+\N|If you need to add additional packages and are doing this one package at a
+time (for example, first library then executable in the \"library and
+executable\" project), then this is the point where you would want to restart
+from \l{#core-package Create package and generate \c{buildfile} templates} for
+another iteration. Only once all the packages are added does it make sense
+to continue with updating project \c{README.md}.|
+
+@@ Purpose.
+
+@@ Commit and push.
+
 \h#core-release-publish|Release and publish|
 
 Once all the adjustments are in and everything is tested, we can release the