general boilerplate / project-support improvements (#16)

Author: synesissoftware

.github/workflows/ci.yml

@@ -3,15 +3,13 @@ name: CI
 on:
   push:
     branches:
-      - master
-      - dev
       - boilerplate
+      - dev
+      - idiomatic
+      - master
       - rc1
       - rc2
       - rc3
-      - rc4
-      - rc5
-      - update
   pull_request:
 
 concurrency:

.gitignore

@@ -54,12 +54,10 @@ perf_test/
 
 scripts/internal/
 
-/include/b64/
 /include/shwild/
 /include/xcontract/
 /include/xcover/
 /include/xtests/
-/src/b64/
 /src/shwild/
 /src/xcontract/
 /src/xcover/

.sis/project_name.txt

@@ -0,0 +1 @@
+cstring

AUTHORS.md

@@ -1,12 +1,12 @@
 # cstring - Authors <!-- omit in toc -->
 
 
-## Major Contributors
+## Major Contributors:
 
-* Matt Wilson ([mwsis](https://github.com/mwsis))
+* **Matt Wilson** ([mwsis](https://github.com/mwsis));
 
 
-## Defect reports, fixes and suggestions (for which we are very grateful)
+## Defect reports, fixes and suggestions (for which we are very grateful):
 
 * \<none>
 

CHANGES.md

@@ -1,6 +1,20 @@
 # cstring - CHANGES <!-- omit in toc -->
 
 
+## 4.0.14-alpha1 - 7th August 2026
+
+* Aligned project boilerplate with **b64** / **Pantheios** (scripts, markdown, CI branches, `.sis`);
+* Added **.sis/project_name.txt**; helper scripts load `ProjectName` for status echoes;
+* CI `on.push.branches` set to lexicographic Pantheios set (`boilerplate`, `dev`, `idiomatic`, `master`, `rc1`–`rc3`);
+* **CMakeLists.txt** — set `CMP0177` for CMake ≥ 3.31;
+* **.gitignore** — removed stray **b64** include/src ignore entries;
+* **README.md** — C++ badge; CI badge alt text; **Introduction**; help links; heading fixes;
+* **AUTHORS.md**, **NEWS.md**, **FAQ.md**, **KNOWN_ISSUES.md** — peer layout/content alignment;
+* Added **HOW_YOU_CAN_HELP.md**;
+* **TODO.md** — marked `CMAKE_INSTALL_LIBDIR` complete;
+* **run_all_examples.sh**, **run_all_unit_tests.sh**, **run_all_scratch_tests.sh** — coloured list/execute path output (via `tput`);
+
+
 ## 4.0.13 - 2nd August 2026
 
 * Modular GitHub Actions CI (**ci.yml** + **ci-cell.yml**), with install-smoke and MinGW cells;

CMakeLists.txt

@@ -5,7 +5,7 @@
 # Purpose:  Top-level CMake lists file for cstring
 #
 # Created:  21st December 2023
-# Updated:  2nd August 2026
+# Updated:  6th August 2026
 #
 # ######################################################################## #
 
@@ -14,6 +14,9 @@
 # CMake
 
 cmake_minimum_required(VERSION 3.20 FATAL_ERROR)
+if(CMAKE_VERSION VERSION_GREATER_EQUAL "3.31")
+	cmake_policy(SET CMP0177 NEW)
+endif()
 
 # require out-of-source builds
 file(TO_CMAKE_PATH "${CMAKE_CURRENT_BINARY_DIR}/CMakeLists.txt" LOC_PATH)

Doxyfile

@@ -2,7 +2,7 @@
 
 PROJECT_NAME           = "cstring"
 PROJECT_BRIEF          = "Extensible C-style strings and vectors of such, for Unix and Windows"
-PROJECT_NUMBER         = 4.0.13
+PROJECT_NUMBER         = 4.0.14-alpha1
 
 # Prefer SIS_CMAKE_BUILD_DIR-aligned output (same convention as Diagnosticism).
 # ./dox/ remains gitignored for legacy/local runs that override OUTPUT_DIRECTORY.

FAQ.md

@@ -8,9 +8,11 @@ it will be used to create one.
 ## Table of Contents <!-- omit in toc -->
 
 - [Q1: "How do I build cstring?"](#q1-how-do-i-build-cstring)
-- [Q2: "Does cstring have its own unit-tests?"](#q2-does-cstring-have-its-own-unit-tests)
-- [Q3: "How do I build without the C++ examples and tests?"](#q3-how-do-i-build-without-the-c-examples-and-tests)
-- [Q4: "Where are the examples?"](#q4-where-are-the-examples)
+- [Q2: "How do I install cstring?"](#q2-how-do-i-install-cstring)
+- [Q3: "How do I use cstring?"](#q3-how-do-i-use-cstring)
+- [Q4: "Does cstring have its own unit-tests?"](#q4-does-cstring-have-its-own-unit-tests)
+- [Q5: "How do I build without the C++ examples and tests?"](#q5-how-do-i-build-without-the-c-examples-and-tests)
+- [Q6: "Where are the examples?"](#q6-where-are-the-examples)
 
 
 # FAQs: <!-- omit in toc -->
@@ -37,7 +39,48 @@ $ ./prepare_cmake.sh -m
 Execute `$ ./prepare_cmake.sh --help` for the full set of options.
 
 
-## Q2: "Does cstring have its own unit-tests?"
+## Q2: "How do I install cstring?"
+
+See [INSTALL.md](./INSTALL.md) for details of how to install **cstring**.
+
+
+## Q3: "How do I use cstring?"
+
+Include **cstring/cstring.h** (and **cstring/cstring.vector.h** where needed)
+and link against **libcstring** (the **CMake** target is `cstring::core`).
+Create and destroy instances with `cstring_create()` / `cstring_destroy()`,
+and mutate with `cstring_assign()`, `cstring_append()`, and related APIs.
+
+A minimal sketch:
+
+```c
+#include <cstring/cstring.h>
+
+#include <stdio.h>
+#include <stdlib.h>
+
+int main(void)
+{
+    cstring_t cs;
+    CSTRING_RC rc = cstring_create(&cs, "Hello");
+
+    if (CSTRING_RC_SUCCESS != rc)
+    {
+        return EXIT_FAILURE;
+    }
+
+    printf("%s\n", cs.ptr);
+
+    cstring_destroy(&cs);
+
+    return EXIT_SUCCESS;
+}
+```
+
+See [INSTALL.md](./INSTALL.md) and the examples under **examples/**.
+
+
+## Q4: "Does cstring have its own unit-tests?"
 
 Yes. Automated tests live under:
 
@@ -50,7 +93,7 @@ and run with **run_all_unit_tests.sh** (and **CTest** where configured). Tests
 require **STLSoft** and **xTests** (and may optionally recognise **shwild**).
 
 
-## Q3: "How do I build without the C++ examples and tests?"
+## Q5: "How do I build without the C++ examples and tests?"
 
 Pass `--no-cpp` (or `-C`) to **prepare_cmake.sh**, which sets CMake
 `NO_CSTRING_CPP_API=ON`. That omits C++ examples and remaining C++ tests.
@@ -59,7 +102,7 @@ The **C** unit-tests still require **STLSoft** and **xTests** unless you also
 pass `--disable-testing` / `-T`.
 
 
-## Q4: "Where are the examples?"
+## Q6: "Where are the examples?"
 
 Examples live under **examples/** (`c/` and `cpp/`), each with a short
 **README.md**. They are built when `BUILD_EXAMPLES` is on (the default); omit

HOW_YOU_CAN_HELP.md

@@ -0,0 +1,70 @@
+# cstring - How You Can Help <!-- omit in toc -->
+
+
+## Table of Contents <!-- omit in toc -->
+
+There are several ways in which you can help the **cstring** project:
+
+- [Defect reports](#defect-reports)
+- [Feature requests](#feature-requests)
+- [Submit your own extensions](#submit-your-own-extensions)
+- [Sponsor development](#sponsor-development)
+- [Write articles, blog-posts about your experiences](#write-articles-blog-posts-about-your-experiences)
+
+
+## Defect reports
+
+We're keen to hear of any problems you have in building and, especially, in
+using the library.
+
+Please submit an issue at:
+
+  https://github.com/synesissoftware/cstring/issues
+
+Please help us to help you by submitting as much information about the
+problem as you think is relevant, including:
+
+* the compiler you're using;
+* the architecture and operating system you're targeting;
+* the version of **cstring**;
+* the version of **STLSoft** / **xTests** (when building tests);
+* whether you're building using **CMake** or via an IDE;
+* a section of the build output, including the warnings/errors involved;
+
+
+## Feature requests
+
+If there are features that you think would enhance the library, please feel
+free to share your ideas.
+
+You can either submit an issue:
+
+  https://github.com/synesissoftware/cstring/issues
+
+Or provide your suggested work via a pull-request:
+
+  https://github.com/synesissoftware/cstring/pulls
+
+
+## Submit your own extensions
+
+If you have developed extensions or improvements and wish to contribute them
+back to the project so others can benefit from your work, please open an
+issue or pull request at:
+
+  https://github.com/synesissoftware/cstring
+
+
+## Sponsor development
+
+If you value the diligence and effort that's gone into bringing you this
+production-quality software, please get in contact via
+https://www.synesis.com.au/contact.html
+
+
+## Write articles, blog-posts about your experiences
+
+If you've written articles or blogged about **cstring**, let us know.
+
+
+<!-- ########################### end of file ########################### -->

KNOWN_ISSUES.md

@@ -1,7 +1,12 @@
 # cstring - Known Issues <!-- omit in toc -->
 
 
-## cstring 4 Known Issues
+## cstring 4.0.x Known Issues
+
+* \<none>
+
+
+## cstring 4.0.x Suspected Issues
 
 * \<none>