Write the first revision of Progmasoft C++ Style

Progmasoft C++ Style is a style guide for C++20, written for anyone
who wants a complete rule set to adopt. It writes down the conventions
the Progmasoft C++ projects already follow (naming, the clang-format
and clang-tidy profiles, exception-free error handling, Doxygen) and
decides what they left open.

Thirteen chapters under Guide/:

1. Principles: what the guide optimizes for and how to decide a case
   it does not cover.
2. Formatting: the full .clang-format profile, the reason for each
   choice, and the rules the tool cannot apply.
3. Naming: casing for every kind of name, acronyms, choosing words,
   namespaces, files.
4. Files and headers: extensions, #pragma once, includes, what goes in
   a header, the order inside a class, file size, vendored code.
5. Language: functions, auto, initialization, const and constexpr,
   casts, integers, strings, enumerations, templates and concepts,
   lambdas, control flow, and the features not used.
6. Types and classes: struct or class, final, construction, the rule of
   zero, inheritance, operators, strong types, optional and variant.
7. Errors: no exceptions by default, Expected and Error, invariants,
   fatal defects, destructors, diagnostics.
8. Ownership and memory: owners and borrowers, views and lifetimes,
   RAII, containers and deterministic iteration, allocation, undefined
   behavior.
9. Comments and documentation: Doxygen for public declarations,
   comments that explain why, TODOs that name an issue.
10. C interfaces: C11 headers, prefixes, opaque types, ownership and
    failure across the boundary, stability.
11. Concurrency: sharing less, threads, locks, thread-safety
    annotations, atomics, statics.
12. Testing: unit tests, fuzzing, sanitizers, benchmarks, coverage.
13. Tooling: the compiler flags, the full .clang-tidy profile with the
    reason for every disabled check, other checks, version pinning.

The guide prescribes no test, fuzzing or benchmark framework and no
error library; it prescribes how they are used. ADOPTING.md explains
how a project points to the guide, copies the profiles and records its
deviations. CONTRIBUTING.md explains how to propose a change.

The text is licensed under CC BY 4.0. The configuration and code
examples are dedicated to the public domain under CC0 1.0, so projects
can copy them under their own license.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 63 insertions, 0 deletions

diff --git a/ADOPTING.md b/ADOPTING.md
new file mode 100644
index 0000000..2fc3f12
--- /dev/null
+++ b/ADOPTING.md
@@ -0,0 +1,63 @@
+<!-- SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com> -->
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+
+# Adopting the guide
+
+A project adopts Progmasoft C++ Style by pointing to it, copying its two tool profiles and writing down, once, where it
+deviates.
+
+## 1. Point to the guide
+
+Add a short section to the project's contributing guide:
+
+```markdown
+## C++ style
+
+C++ code follows [Progmasoft C++ Style](https://github.com/Progmasoft/progmasoft-cpp).
+`clang-format` and `clang-tidy` enforce what they can; review covers the rest.
+Deviations of this project are listed below.
+```
+
+Do not copy the rules into the project. A copy drifts from the guide, and two documents that disagree are worse than
+one.
+
+## 2. Copy the profiles
+
+| File | From |
+| --- | --- |
+| `.clang-format` | [Formatting: the profile](Guide/FORMATTING.md#the-profile) |
+| `.clang-tidy` | [Tooling: the clang-tidy profile](Guide/TOOLING.md#132-the-clang-tidy-profile), with the path filters set to the project's directories |
+| compiler flags | [Tooling: flags](Guide/TOOLING.md#flags), in the build files of the project |
+
+The profiles are in the public domain (see [LICENSE.md](LICENSE.md)), so they can be copied under the project's own
+license. Note the guide revision they come from in a comment at the top of each file, so a later update can be compared.
+
+## 3. Record the deviations
+
+Every project has a few rules of its own: a namespace root, an include prefix, a test framework, a component that must
+use exceptions because its host does. List them in the contributing guide, each with its reason:
+
+```markdown
+### Deviations
+
+- The intermediate representations use the lowercase namespaces `tala::core`, `tala::xpp` and `tala::xmm`, because
+  they are qualified on almost every line of the compiler (Naming, 3.4).
+- Assertion failures are reported by throwing, as the Catch2 API requires; exceptions stay inside the library
+  (Errors, 7.1).
+```
+
+Within the project, its documented rule wins over the guide. An undocumented difference is not a deviation; it is code
+that has not caught up yet.
+
+## 4. Converge gradually
+
+Existing code is not rewritten in one sweep. A file follows the guide where it is changed. A purely mechanical change,
+such as applying `clang-format` to a directory or renaming a member convention, is its own pull request, never mixed
+with a change in behavior, so that review and `git blame` stay useful.
+
+## Projects that follow the guide
+
+| Project | Deviations recorded in |
+| --- | --- |
+| [Progmasoft/tala](https://github.com/Progmasoft/tala) | `Documents/Contributing/STYLE-AND-LICENSING.md` |
+| [Progmasoft/catch3](https://github.com/Progmasoft/catch3) | the Progmasoft-authored sources under `src/Progmasoft/`; code derived from Catch2 keeps its upstream style |