From c303f32b36d5710f48f4ca34dbffeb7f49034c88 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Tue, 30 Jan 2024 09:43:10 +0200
Subject: Further work on packaging guide

---
 doc/packaging.cli | 84 +++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 63 insertions(+), 21 deletions(-)

(limited to 'doc')

diff --git a/doc/packaging.cli b/doc/packaging.cli
index 6b1fdb5..bc83dfd 100644
--- a/doc/packaging.cli
+++ b/doc/packaging.cli
@@ -10,9 +10,6 @@
 // - Maximum <pre> line is 70 characters.
 //
 // - In guideline titles (do/don't) omit a/the.
-//
-
-// @@ Close the issue in WISHLIST.
 
 "
 \h0#preface|Preface|
@@ -217,7 +214,7 @@ push.|
 
 \N|While you can use any name for a repository under the personal workspace,
 under \l{https://github.com/build2-packaging github.com/build2-packaging} it
-should follow the \l{core-repo-name Use upstream repository name as package
+should follow the \l{#core-repo-name Use upstream repository name as package
 repository name} guideline. In particular, there should be no prefixes like
 \c{build2-} or suffixes like \c{-package}. If the repository under your
 personal workspace does not follow this guideline, you should rename it before
@@ -3202,7 +3199,40 @@ $ bdep ci
 Once all the adjustments are in and everything is tested, we can finally
 release the final version of the package as well as publish it to
 \l{https://cppget.org cppget.org}. Both of these steps are automated with the
-corresponding \c{bdep} commands.
+corresponding \c{bdep} commands. But before performing these steps we need to
+transfer the package repository to \l{https://github.com/build2-packaging
+github.com/build2-packaging}.
+
+
+\h2#core-release-publish-transfer|Transfer package repository|
+
+If you have been doing your work in a repository in your personal workspace,
+then now is the time to transfer it to the
+\l{https://github.com/build2-packaging github.com/build2-packaging}
+organization.
+
+\N|It is important to transfer the repository before publishing the first
+version of the package since the repository is used as a proxy for package
+name ownership (see \l{bdep-publish(1)} for details). If you publish the
+package from your personal workspace and then transfer the repository, the
+ownership information will have to be adjusted manually, which we would
+prefer to avoid.|
+
+First you will need to become a member of this organization. This will give
+you permissions to create new repositories, which is required to perform a
+tranfer (you will also have full read/write access to the repository once
+transferred). To get an invite, \l{https://build2.org/community.xhtml#help get
+in touch} not forgetting to mention your GitHub user name.
+
+Then, if your repository has any prefixes, such as \c{build2-}, or suffixes
+such as \c{-package}, then the first step is to rename it to follow the
+\l{#core-repo-name Use upstream repository name as package repository name}
+guideline. Go to the repository's Settings on GitHub where you should see the
+Rename button.
+
+Finally, to perform the transfer, go to the repository's Settings, Danger Zone
+section, where you should see the Transfer button. Select \c{build2-packaging}
+as the organization to transfer to, and complete the transfer.
 
 
 \h2#core-release-publish-release|Release final version|
@@ -3212,6 +3242,9 @@ the upstream version (see \l{#core-package-adjust-version Adjust package
 version}). Once all the changes are in, we can change to the final upstream
 version, in a sense signalling that this package version is ready.
 
+\N|If you are working in a branch, then now is the time to merge it into
+\c{master}.|
+
 The recommended way to do this is with the \l{bdep-release(1)} command (see
 \l{intro#guide-versioning-releasing Versioning and Release Management} for
 background). Besides replacing the \c{version} value in the package
@@ -3278,6 +3311,11 @@ revision} to address these problems. But in both cases you should first read
 through \l{#core-version-management Package version management} to understand
 the recommended \"version lifecycle\" of a third-party package.
 
+Also, if there is an issue for this package in
+\l{https://github.com/build2-packaging/WISHLIST
+github.com/build2-packaging/WISHLIST}, then you would want to add a comment
+and close it once the package has been published.
+
 
 \h#core-version-management|Package version management|
 
@@ -3343,6 +3381,11 @@ release revisions to fix issues in the package \"infrastructure\"
 (\c{buildfiles}, \c{manifest}, etc) as well as critical bugs in upstream
 source code.
 
+\N|Releasing a new revision is also a good opportunity to review and fix any
+accumulated issues that didn't warrant a revision on their own. See
+\l{#core-version-management-new-version-issues New version: review/fix
+accumulated issues} for background.|
+
 In the revision phase of the package version lifecycle (i.e., when the version
 does not end with \c{-a.0.z}), every commit must be accompanies by the
 revision increment to maintain continous verisions. As a result, each revision
@@ -3579,6 +3622,19 @@ similar to the \l{#core-root-buildfile Adjust root \c{buildfile}} and
 initial packaging steps.
 
 
+\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
+always be able to fix it immediately (for example, by
+\l{#core-version-management-new-revision releasing a revision}). This could be
+because the change is too extensive/risky for a revision or simply not
+critical enough to warrant a release. In such cases it's recommended to file
+an issue in the package's repository with the view to fix it when the next
+opportunity arises. Releasing a new upstream version is one such opportunity
+and it makes sense to review any accumulated package issues and see if any
+of them can be addressed.
+
+
 \h2#core-version-management-new-version-test|New version: test locally and with CI|
 
 Once all the adjustments are in, test the package both locally and with CI
@@ -3605,13 +3661,6 @@ Then release and publish using the same steps as after the initial packaging:
 \l{#core-release-publish Release and publish}.
 
 
-@@ Maybe in the initial instructions makes sense to identify and note
-the point where to merge the branch to master if working in a branch
-(e.g., because of a new version).
-
-@@ Add item to review issues in case good opportunity to fix any.
-
-
 \h2#core-version-management-old-series|New version/revision in old release series|
 
 As discussed in \l{#core-version-management Package version management}, if we
@@ -3650,17 +3699,10 @@ released \c{2.1.0}. In this case it makes sense to call the branch \c{2} since
 it corresponds to the \c{2.Y.Z} release series. If you already have the
 \c{2.1} branch, then it makes sense to rename it to \c{2}.|
 
-
-
-@@ Enforce continous versioning?
-
-@@ When do we transfer the repository to build2-packaging? Should not
-   publish until then.
-
-@@ GH issue #?? has some notes.
-
 ========
 
+@@ Enforce continous versioning with pre-commit hook -- maybe add a note?
+
 @@ Add example of propagating config.libfoo.debug to macro on build options?
 
 @@ Note on library metadata where talk about configuration. Also about
-- 
cgit v1.1