From f056eba05a1c782dc203a163bd0e4925fc6271d9 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Tue, 10 Oct 2023 08:21:04 +0200
Subject: Add FAQ entry to packaging guide

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

diff --git a/doc/packaging.cli b/doc/packaging.cli
index 356cfc4..0363e9a 100644
--- a/doc/packaging.cli
+++ b/doc/packaging.cli
@@ -281,4 +281,56 @@ LAYOUT} for details):
 $ bdep new -t lib,prefix=libigl-core,no-subdir,no-version libigl-core
 \
 
+
+\h1#faq|Packaging FAQ|
+
+\h#faq-publish-stage|Where to publish if package requires staged toolchain?|
+
+If your package requires the \l{https://build2.org/community.xhtml#stage staged
+toolchain}, for example, because it needs a feature or bugfix that is not yet
+available in the released toolchain, then you won't be able to publish it to
+\c{cppget.org}. Specifically, if your package has the accurate \c{build2}
+version constraint and you attempt to publish it, you will get an error like
+this:
+
+\
+error: package archive is not valid
+  info: unable to satisfy constraint (build2 >= 0.17.0-) for package foo
+  info: available build2 version is 0.16.0
+\
+
+There are three alternative ways to proceed in this situation:
+
+\ol|
+
+\li|Wait until the next release and then publish the package to
+\c{cppget.org}.|
+
+\li|If the requirement for the staged toolchain is \"minor\", that is, it
+doesn't affect the common functionality of the package or only affects a small
+subset of platforms/compilers, then you can lower the toolchain version
+requirement and publish the package to \c{cppget.org}. For example, if
+you require the staged toolchain because of a bugfix that only affects
+one platform, it doesn't make sense to delay publishing the package
+since it is perfectly usable on all the platforms in the meantime.|
+
+\li|Publish it to \l{https://queue.stage.build2.org queue.stage.build2.org},
+the staging package repository. This repository contain new packages that
+require the staged toolchain to work and which will be automatically
+moved to \c{cppget.org} once the staged version is released. The other
+advantage of publishing to this repository (besides not having to remember
+to manually publish the package once the staged version is released) is
+that your package becomes available from an archive repository (which is
+substantially faster than a \c{git} repository).
+
+To publish to this repository, use the following \c{bdep-publish} command
+line:
+
+\
+$ bdep publish --repository=https://stage.build2.org ...
+\
+
+||
+
+
 "
-- 
cgit v1.1