diff options
| -rw-r--r-- | doc/packaging.cli | 51 |
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? |