Further work on packaging guide

1 files changed, 91 insertions, 40 deletions

diff --git a/doc/packaging.cli b/doc/packaging.cli
index f5cfbe4..450a450 100644
--- a/doc/packaging.cli
+++ b/doc/packaging.cli
@@ -1029,32 +1029,46 @@ and removing (or editing, if you have multiple packages and only want to redo
 some of them) \c{packages.manifest} and starting over.|
 
 This time, however, we will do things a bit differently in order to take
-advantage of some additional automation offered by \c{bdep-new}. If the
-package directory already exists and contains certain files, \c{bdep-new} can
-take this into account when generating the root \c{buildfile} and package
-\c{manifest}. In particular, it will try to guess the license from the
-\c{LICENSE} file and extract the summary from \c{README.md} and use this
-information in \c{manifest}.
+advantage of some additional automation offered by \c{bdep-new}.
+
+Firstly, we will use the special \c{third-party} sub-option which is meant for
+converting third-party projects to \c{build2}. Specifically, this sub-option
+automatically enables \c{no-version} and \c{no-symexport} unless
+\c{auto-symexport} is specified. It also adds a number of values to
+\c{manifest} that makes sense to specify in a package of a third-party
+project. Finally, it generates the \c{PACKAGE-README.md} template which
+describes how to use the package from a \c{build2}-based project (see the
+\l{bpkg#manifest-package-description \c{package-description}} \c{manifest}
+value for background).
+
+Secondly, if the package directory already exists and contains certain files,
+\c{bdep-new} can take this into account when generating the root \c{buildfile}
+and package \c{manifest}. In particular, it will try to guess the license from
+the \c{LICENSE} file and extract the summary from \c{README.md} and use this
+information in \c{manifest} as well as generated \c{PACKAGE-README.md}.
 
 \N|If the file names or formats used by upstream don't match those recognized
-by \c{bdep-new} or if an attempt to extra the information is unsuccessful,
-then for now simply omit the corresponding files from the package directory
-and add them later manually.
+by \c{bdep-new}, then for now simply omit the corresponding files from the
+package directory and add them later manually. Similarly, if an attempt to
+extra the information is unsuccessful, we will have a chance to adjust it in
+\c{manifest} later.
 
-Specifically, for \c{README}, \c{bdep-new} only recognizes \c{README.md}.
+Specifically, for \c{README}, \c{bdep-new} recognizes \c{README.md},
+\c{README.txt} and \c{README} but will only attempt to extract the summary
+from \c{README.md}.
 
 For license files, \c{bdep-new} recognizes \c{LICENSE}, \c{LICENSE.txt}
 \c{LICENSE.md}, \c{COPYING}, and \c{UNLICENSE}.
 
-
-@@ TODO: PACKAGE-README.md and README-PACKAGE.md (and below)
-
-|
+For changes files, \c{bdep-new} recognizes \c{NEWS}, \c{CHANGES}, and
+\c{CHANGELOG} in various cases as well as with the \c{.md}, \c{.txt}
+extensions.|
 
 Continuing with our \c{libfoo} example and assuming upstream provides the
-\c{README.md} and \c{LICENSE} files, we first manually create the package
-directory, then add the symlinks, and finally run \c{bdep-new} (notice that we
-have omitted the package name from the \c{bdep-new} command line since we are
+\c{README.md}, \c{LICENSE}, and \c{NEWS} files, we first manually create the
+package directory, then add the symlinks, and finally run \c{bdep-new} (notice
+that we have replaced \c{no-version} and \c{no-symexport} with \c{third-party}
+and omitted the package name from the \c{bdep-new} command line since we are
 running from inside the package directory):
 
 \
@@ -1066,15 +1080,46 @@ $ mkdir libfoo/
 $ cd libfoo/ # Change to the package root.
 $ ln -s ../upstream/README.md ./
 $ ln -s ../upstream/LICENSE   ./
+$ ln -s ../upstream/NEWS      ./
 
-$ bdep new --package                            \
-  --lang c++,cpp   \
-  --type lib,split,subdir=foo,no-subdir-source,no-version,no-symexport
+$ bdep new --package \
+  --lang c++,cpp     \
+  --type lib,split,subdir=foo,no-subdir-source,third-party
 \
 
-If auto-detection succeeds, then you should see the \c{summary} and
-\c{license} values automatically populated in \c{manifest} and the symlinked
-files listed in the root \c{buildfile}.
+The final contents of our package will look like this:
+
+\
+$ cd ../
+$ tree libfoo/
+libfoo/
+├── build/
+│   └── ...
+├── include/
+│   └── foo/
+│       ├── buildfile
+│       └── foo.hpp
+├── src/
+│   ├── buildfile
+│   └── foo.cpp
+├── tests/
+│   ├── build/
+│   │   └── ...
+│   ├── basics/
+│   │   ├── buildfile
+│   │   └── driver.cpp
+│   └── buildfile
+├── buildfile
+├── manifest
+├── NEWS       -> ../upstream/NEWS
+├── LICENSE    -> ../upstream/LICENSE
+├── README.md  -> ../upstream/README.md
+└── PACKAGE-README.md
+\
+
+If auto-detection of \c{README}, \c{LICENSE}, and \c{NEWS} succeeds, then you
+should see the \c{summary} and \c{license} values automatically populated in
+\c{manifest} and the symlinked files listed in the root \c{buildfile}.
 
 
 \h2#core-package-adjust-version|Adjust package version|
@@ -1355,7 +1400,8 @@ $ git commit -m \"Add dependencies\"
 Now we are ready to begin replacing the \c{bdep-new}-generated files with
 upstream source code symlinks and we start with library's header and source
 files. Continuing with our \c{libfoo} example, this is what we currently have
-(notice that \c{LICENSE} and \c{README.md} are already symlinks to upstream):
+(notice that \c{LICENSE}, \c{README.md}, and \c{NEWS} are already symlinks to
+upstream):
 
 \
 $ cd foo/ # Change to the package repository root.
@@ -1373,10 +1419,12 @@ libfoo/
 │   └── foo.cpp
 ├── tests/
 │   └── ...
-├── LICENSE   -> ../upstream/LICENSE
-├── README.md -> ../upstream/README.md
 ├── buildfile
-└── manifest
+├── manifest
+├── NEWS       -> ../upstream/NEWS
+├── LICENSE    -> ../upstream/LICENSE
+├── README.md  -> ../upstream/README.md
+└── PACKAGE-README.md
 \
 
 Now we replace generated \c{include/foo/foo.hpp} with library's real headers
@@ -2859,28 +2907,28 @@ The main function of the root \c{buildfile} is to pull all the subdirectories
 that need building plus list targets that are usually found in the root
 directory of a project, typically \c{README.md}, \c{LICENSE}, etc. This is
 what the generated root \c{buildfile} looks like for our \c{libfoo} project
-assuming we have symlinked \c{README.md} and \c{LICENSE} from upstream on the
-\l{#core-package-create Create final package} step:
-
-@@ PACKAGE-README.md?
+assuming we have symlinked \c{README.md}, \c{LICENSE}, and \c{NEWS} from
+upstream on the \l{#core-package-create Create final package} step:
 
 \
-./: {*/ -build/} doc{README.md} legal{LICENSE} manifest
+./: {*/ -build/}                          \
+    doc{README.md PACKAGE-README.md NEWS} \
+    legal{LICENSE} manifest
 
 # Don't install tests.
 #
 tests/: install = false
 \
 
-If the upstream project provides any other documentation (change log, news,
-etc) or legal files (list of authorts, code of conduct, etc), then you may
-want to symlink and list them as the \c{doc{\}} and \c{legal{\}}
-prerequisites, respectively.
+If the upstream project provides any other documentation (detailed change
+logs, contributing guidelines, etc) or legal files (list of authorts, code of
+conduct, etc), then you may want to symlink and list them as the \c{doc{\}}
+and \c{legal{\}} prerequisites, respectively.
 
 \N|One file you don't need listing is \c{INSTALL} (or equivalent) which
 normally contains the installation instructions for the upstream build
 system. In the \c{build2} package the \c{PACKAGE-README.md} file serves this
-purpose.|
+purpose (see @@ ref to where we adit it).|
 
 
 \h2#core-root-buildfile-doc|Adjust root \c{buildfile}: other subdirectories|
@@ -2918,8 +2966,9 @@ the \c{*.md} files as prerequisites using the \c{doc{\}} target type (which,
 in particular, makes sure they are installed into the appropriate location):
 
 \
-./: {*/ -build/ -docs/} \
-    doc{README.md} docs/doc{*.md} \
+./: {*/ -build/ -docs/}                   \
+    doc{README.md PACKAGE-README.md NEWS} \
+    docs/doc{*.md}                        \
     legal{LICENSE} manifest
 \
 
@@ -3292,7 +3341,7 @@ The \c{bdep-publish} command prepares the source distributin of your package,
 uploads the resulting archive to the package repository, and prints a link to
 the package submission in the queue. Open this link in the browser and check
 that there are no surprises in build results (they should match the earlier CI
-results) or in the displayed package information (\c{README.md}, etc).
+results) or in the displayed package information (\c{PACKAGE-README.md}, etc).
 
 \N|While there should normally be no discrepancies in the build results
 compared to our earlier CI submissions, the way the packages are built on CI
@@ -3701,6 +3750,8 @@ 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?