more pro forma changes before graduation (#19)

* more pro forma changes before graduation

* responding to comments

Author: thirtytwobits

.vscode/settings.json

@@ -33,7 +33,9 @@
         "/polyfill/i",
         "/autosar/i",
         "/__cplusplus/",
-        "/<cassert>/"
+        "/<cassert>/",
+        "/godbolt/i",
+        "/cppreference/"
     ],
     "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools",
     "cmake.configureOnOpen": false,

CONTRIBUTING.md

@@ -1,3 +1,17 @@
+# Proposing a New Type
+
+If you want to add to CETL you should start on the [forum](https://forum.opencyphal.org/c/app/cetl/22). Once we have
+tacit approval the type should be developed using a [standard Github workflow](https://docs.github.com/en/get-started/quickstart/contributing-to-projects).
+
+> Please don't write code on the forum. The forum post should be used to build consensus that a given type should be
+developed and contributed to CETL before you go wasting your time writing the code. Once you have that level of support
+it's time to move to Github.
+
+For some types, however, we may want to stage introduction but make the type available to maintainers and
+early-adopters. To facilitate git submodule access to CETL and to avoid noise we use feature branches upstream to
+incubate such types. As such, we may request that your PR to `main` be redirected to a feature branch we setup in the
+form of `preview/{your incubating feature name}`.
+
 # Running CETLVaSt
 
 ```

cetlvast/suites/compile/test_cetl_h_erase.cpp

@@ -0,0 +1,21 @@
+/// @file
+/// Compile test that ensures CETL_H_ERASE works as intended.
+///
+/// @copyright
+/// Copyright (C) OpenCyphal Development Team  <opencyphal.org>
+/// Copyright Amazon.com Inc. or its affiliates.
+/// SPDX-License-Identifier: MIT
+///
+
+
+#ifndef CETLVAST_COMPILETEST_PRECHECK
+#define CETL_H_ERASE
+#endif
+
+// this should have an error macro that prevents compilation.
+#include "cetl/cetl.hpp"
+
+int main()
+{
+    return 0;
+}

include/cetl/cetl.hpp

@@ -1,20 +1,59 @@
 /// @file
 /// CETL common header.
 ///
+/// @copyright
+/// Copyright (C) OpenCyphal Development Team  <opencyphal.org>
+/// Copyright Amazon.com Inc. or its affiliates.
+/// SPDX-License-Identifier: MIT
+///
 /// @note
 /// Keep this very spare. CETL's desire is to adapt to future C++ standards
 /// and too many CETL-specific definitions makes it difficult for users to switch off of CETL in the
 /// future.
 ///
-/// @copyright
-/// Copyright (C) OpenCyphal Development Team  <opencyphal.org>
-/// Copyright Amazon.com Inc. or its affiliates.
-/// SPDX-License-Identifier: MIT
+/// If `CETL_H_ERASE` is defined then all CETL types will exclude the `cetl/cetl.hpp` header which
+/// removes all common dependencies, other than C++ standard headers, from CETL. The types will not build due to
+/// missing macros but the user can re-define these based on subsequent compiler errors. This allows elision of
+/// cetl.hpp without modifying CETL source code. The CETL types are not guaranteed to work with cetl.hpp removed; you
+/// have been warned.
+///
+/// @warning
+/// polyfill headers cannot be used if CETL_H_ERASE is defined. Presumably, if you really want to minimize your
+/// dependencies, you would not be using the polyfill headers.
 ///
 
 #ifndef CETL_H_INCLUDED
 #define CETL_H_INCLUDED
 
+#ifdef CETL_H_ERASE
+#    error "CETL_H_ERASE was defined. This header should never be included when the build is trying to erase it!"
+#endif
+
+/// @defgroup CETL_VERSION The semantic version number of the CETL library.
+/// These macros are an AUTOSAR-14 Rule A16-0-1 violation but we feel it necessary to provide them.
+/// @{
+
+/// @def CETL_VERSION_PATCH
+/// CETL Patch version.
+/// Patch versions shall always be backwards compatible with the same major
+/// and minor version. A patch version number change will only occur if library source code is changed.
+/// Documentation or test suite changes will not require a change to `cetl/cetl.hpp` and will not bump
+/// the patch version.
+#define CETL_VERSION_PATCH 0
+
+/// @def CETL_VERSION_MINOR
+/// CETL minor version.
+/// Minor versions shall only add to CETL or modify it in a backwards compatible way.
+#define CETL_VERSION_MINOR 0
+
+/// @def CETL_VERSION_MAJOR
+/// CETL Major version.
+/// New major versions shall be rare. No overarching guarantees are made about compatibility
+/// between major versions.
+#define CETL_VERSION_MAJOR 0
+
+/// @}
+
 /// @def CETL_DEBUG_ASSERT
 /// When `CETL_ENABLE_DEBUG_ASSERT` is defined and not 0 then this is redirected to
 /// assert as included from `<cassert>`. Because assert does not support a failure message
@@ -36,13 +75,18 @@
 #    define CETL_DEBUG_ASSERT(c, m) ((void) m)
 #endif  // CETL_ENABLE_DEBUG_ASSERT
 
-// For example: https://godbolt.org/z/Thsn8qf1a
-// We define these in a common header since we might encounter odd values on some compilers that we'll have to
-// provide special cases for.
-
 /// @defgroup CETL_CPP_STANDARD Guaranteed CETL c++ standard numbers
 /// These macros are an AUTOSAR-14 Rule A16-0-1 violation but can be used to conditionally include headers which
-/// is compliant with A16-0-1.
+/// is compliant with A16-0-1. The values were obtained by observation of compiler output using
+/// [godbolt](https://godbolt.org/z/Thsn8qf1a) and as predicted by
+/// [cppreference.com](https://en.cppreference.com/w/cpp/preprocessor/replace#Predefined_macros).
+///
+/// @note
+/// Some CETL types don't use these values directly to reduce the number of explicit dependencies on cetl.hpp but by
+/// including `cetl/cetl.hpp` these types inherit the static assertions that the only valid values of `__cplusplus`
+/// found are one of the the list found in this group or a value greater than the target support `CETL_CPP_STANDARD_20`
+/// value.
+///
 /// @{
 
 /// @def CETL_CPP_STANDARD_14
@@ -76,4 +120,14 @@
 #define CETL_CPP_STANDARD_20 202002L
 
 /// @}
+
+// Ensure base support.
+static_assert(__cplusplus >= CETL_CPP_STANDARD_14,
+              "Unsupported language: ISO C14, C++14, or a newer version of either is required to use this type.");
+
+// Detect weird versions
+static_assert(__cplusplus == CETL_CPP_STANDARD_14 || __cplusplus == CETL_CPP_STANDARD_17 ||
+                  __cplusplus >= CETL_CPP_STANDARD_20,
+              "Unknown __cplusplus value found?");
+
 #endif  // CETL_H_INCLUDED

include/cetl/pf20/span.hpp

@@ -16,7 +16,9 @@
 #include <limits>
 #include <type_traits>
 
-#include "cetl/cetl.hpp"
+#ifndef CETL_H_ERASE
+#    include "cetl/cetl.hpp"
+#endif
 
 namespace cetl
 {
@@ -329,7 +331,7 @@ class span
     /// If the span has a zero size or not.
     /// @return true if the span size is 0 where "size" is the same as span::extent
     /// for this specialization.
-#if (__cplusplus >= CETL_CPP_STANDARD_17)
+#if (__cplusplus >= 201703L)
     [[nodiscard]]
 #endif
     constexpr bool
@@ -687,7 +689,7 @@ class span<T, dynamic_extent>
     ///
     /// Returns if the span has a zero size or not.
     /// @return true if the span size is 0.
-#if (__cplusplus >= CETL_CPP_STANDARD_17)
+#if (__cplusplus >= 201703L)
     [[nodiscard]]
 #endif
     constexpr bool