Merge remote-tracking branch 'upstream/master' into feature/audio-examples

Author: rothmichaels

.clang-tidy

@@ -30,6 +30,7 @@ Checks: '
     -misc-include-cleaner,
     -modernize-use-trailing-return-type,
     -modernize-use-designated-initializers,
+    -portability-avoid-pragma-once,
     -readability-identifier-length,
     -readability-isolate-declaration,
     -readability-magic-numbers,

.devcontainer/README.md

@@ -1,19 +1,23 @@
 # GitHub Codespaces Integration for mp-units
 
-This repository is configured to work seamlessly with GitHub Codespaces, providing a
-complete development environment with all compilers and tools pre-installed. The environment
-is built on [custom `trainiteu/mp-units` Docker image](https://github.com/train-it-eu/docker-images/blob/main/mp-units/Dockerfile)
+This repository is configured to work seamlessly with GitHub Codespaces.
+It provides a complete development environment with all compilers and tools pre-installed.
+The environment is built on a [custom `trainiteu/mp-units` Docker image](https://github.com/train-it-eu/docker-images/blob/main/mp-units/Dockerfile)
 which extends the build tool ecosystem with **mp-units**-specific requirements.
 
 ## Docker Image Hierarchy
 
 The development environment is built on a layered Docker image stack:
 
-1. **[`trainiteu/ubuntu`](https://github.com/train-it-eu/docker-images/blob/main/ubuntu/Dockerfile)**: Ubuntu 25.04 (Plucky Puffin) base with essential development tools
-2. **[`trainiteu/cpp`](https://github.com/train-it-eu/docker-images/blob/main/cpp/Dockerfile)**: Adds CMake, Ninja, Python with pipx for tool management
-3. **[`trainiteu/cpp-conan`](https://github.com/train-it-eu/docker-images/blob/main/cpp-conan/Dockerfile)**: Adds Conan 2.x and base compiler profiles
-4. **[`trainiteu/mp-units`](https://github.com/train-it-eu/docker-images/blob/main/mp-units/Dockerfile)**: **mp-units-specific extensions** including:
-   - Extended compiler matrix (GCC 12-15, Clang 16-20)
+1. **[`trainiteu/ubuntu`](https://github.com/train-it-eu/docker-images/blob/main/ubuntu/Dockerfile)**:
+   Ubuntu 25.04 (Plucky Puffin) base with essential development tools
+2. **[`trainiteu/cpp`](https://github.com/train-it-eu/docker-images/blob/main/cpp/Dockerfile)**:
+   Adds CMake, Ninja, and Python with pipx for tool management
+3. **[`trainiteu/cpp-conan`](https://github.com/train-it-eu/docker-images/blob/main/cpp-conan/Dockerfile)**:
+   Adds Conan 2.x and base compiler profiles
+4. **[`trainiteu/mp-units`](https://github.com/train-it-eu/docker-images/blob/main/mp-units/Dockerfile)**:
+   **mp-units-specific extensions** including:
+   - Extended compiler matrix (GCC 12-15, Clang 16-21)
    - Python documentation ecosystem via pipx
    - Pre-configured Conan remotes and profiles for all compiler combinations
    - Development aliases and optimized build configuration
@@ -52,7 +56,8 @@ The development environment is built on a layered Docker image stack:
 
 3. **Wait for setup**: The container will build automatically (usually 3-5 minutes)
 
-This option provides the same development environment as Codespaces but runs locally on your machine, offering:
+This option provides the same development environment as Codespaces while running locally on
+your machine. It offers:
 - **Full offline development** (after initial setup)
 - **Better performance** on powerful local machines
 - **Direct file system access** for easier integration with local tools
@@ -64,8 +69,8 @@ The development environment includes all compilers and tools used for comprehens
 
 - **Base OS**: Ubuntu 25.04 (Plucky Puffin)
 - **GCC**: 12, 13, 14, 15
-- **Clang**: 16, 17, 18, 19, 20
-- **Standard Library**: libc++-18 for maximum compatibility
+- **Clang**: 16, 17, 18, 19, 20, 21
+- **Standard Library**: libc++-18 for backward compatibility with clang-16
 - **Build Tools**: CMake, Ninja, Conan package manager
 - **Code Quality**: clang-format, clang-tidy, include-what-you-use
 - **Documentation**: MkDocs with Material theme
@@ -79,17 +84,17 @@ The development environment includes all compilers and tools used for comprehens
 The following Conan profiles are pre-configured:
 
 - `gcc12`, `gcc13`, `gcc14`, `gcc15`
-- `clang16`, `clang17`, `clang18`, `clang19`, `clang20`
+- `clang16`, `clang17`, `clang18`, `clang19`, `clang20`, `clang21`
 
 ### Multi-Compiler Testing Script
 
-The Codespace includes a comprehensive testing script at `.devcontainer/check_all.sh`:
+The Codespace includes a comprehensive testing script at `.devcontainer/check_all.sh`.
 
 ```bash
 # Available script options
-./.devcontainer/check_all.sh install   # Install dependencies for all configurations and provide CMake Presets
-./.devcontainer/check_all.sh build     # Build with all compiler configurations
-./.devcontainer/check_all.sh create    # Create Conan packages with all configurations
+./.devcontainer/check_all.sh install   # Install dependencies for all release configurations and provide CMake Presets
+./.devcontainer/check_all.sh build     # Build release with all compiler configurations
+./.devcontainer/check_all.sh create    # Create release Conan packages with all configurations
 ./.devcontainer/check_all.sh -d create # Include debug builds
 ```
 
@@ -114,9 +119,9 @@ The `.devcontainer/api_reference.sh` script automates the generation of API docu
 ```
 
 By default, the script performs both setup and build operations. Use the `-s` flag
-to perform setup only (during development container initialization). The script runs
-automatically during Codespace initialization to ensure the API documentation setup
-is ready.
+to perform setup only (done already during development container initialization).
+The script runs automatically during Codespace initialization to ensure the
+API documentation setup is ready.
 
 The `-d` parameter allows you to specify a custom directory for API documentation
 dependencies. By default, dependencies are stored in `../api_reference_deps` relative
@@ -159,8 +164,9 @@ For current machine specifications and pricing, see:
 - [GitHub Pricing Calculator](https://github.com/pricing/calculator?feature=codespaces)
 
 **Usage Recommendations:**
-- **2-core**: Suitable for documentation, small changes, single compiler testing
-- **4-core**: **Recommended** for most mp-units development - good balance of performance and free usage
+- **2-core**: Suitable for documentation, small changes, and single-profile testing
+- **4-core**: **Recommended** for most mp-units development — good balance of performance
+   and free usage
 - **8-core+**: Best for intensive development sessions or when you need maximum build speed
 
 
@@ -171,7 +177,7 @@ For current machine specifications and pricing, see:
 1. **Start with single profile**: Test your changes with one compiler first
 
    ```bash
-   conan create . -pr clang20 -c user.mp-units.build:all=True -b missing
+   conan create . -pr clang21 -c user.mp-units.build:all=True -b missing
    ```
 
 2. **Test compatibility**: Check the oldest compilers that may have different C++20 support
@@ -196,7 +202,9 @@ For current machine specifications and pricing, see:
 
 ## Getting Help
 
-- Check the [mp-units documentation](https://mpusz.github.io/mp-units/) for project-specific information
-- Refer to the [GitHub Codespaces documentation](https://docs.github.com/en/codespaces) for platform help
+- Check the [mp-units documentation](https://mpusz.github.io/mp-units/)
+  for project-specific information
+- Refer to the [GitHub Codespaces documentation](https://docs.github.com/en/codespaces)
+  for platform help
 - Use the [discussion forums](https://github.com/mpusz/mp-units/discussions) or
   [issues](https://github.com/mpusz/mp-units/issues) in the repository for development questions

.github/FUNDING.yml

@@ -0,0 +1,13 @@
+# These are supported funding model platforms
+
+github: [mpusz]
+# patreon: # Replace with a single Patreon username
+# open_collective: # Replace with a single Open Collective username
+# ko_fi: # Replace with a single Ko-fi username
+# tidelift: # Replace with a single Tidelift package-name
+# community_bridge: # Replace with a single Community Bridge project-name
+# liberapay: # Replace with a single Liberapay username
+# issuehunt: # Replace with a single IssueHunt username
+# otechie: # Replace with a single Otechie username
+# lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name
+# custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,118 @@
+name: 🐛 Bug Report
+description: Create a bug report to help us improve mp-units
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to file a bug report! Please fill out this form as completely as possible.
+
+        **💡 Not sure if this is a bug?** Consider asking in [Discussions](https://github.com/mpusz/mp-units/discussions) first for help and clarification.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of what the bug is.
+      placeholder: Describe the issue you're experiencing...
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Steps to reproduce the behavior
+      placeholder: |
+        1. Include minimal code example
+        2. Compilation command used
+        3. Error message received
+      value: |
+        ```cpp
+        // Minimal reproducible example
+        ```
+    validations:
+      required: true
+
+  - type: input
+    id: compiler_explorer
+    attributes:
+      label: 🚀 Compiler Explorer Link (Recommended)
+      description: |
+        Please provide a Compiler Explorer link demonstrating the issue if possible.
+        This helps us reproduce and understand the problem quickly!
+      placeholder: "https://godbolt.org/z/your-example-link"
+
+  - type: dropdown
+    id: compiler
+    attributes:
+      label: Compiler
+      description: Which compiler are you using?
+      options:
+        - GCC 12
+        - GCC 13
+        - GCC 14
+        - GCC 15
+        - Clang 16
+        - Clang 17
+        - Clang 18
+        - Clang 19
+        - Clang 20
+        - Clang 21
+        - MSVC 194
+        - Apple Clang 15
+        - Apple Clang 16
+        - Other (specify in additional context)
+    validations:
+      required: true
+
+  - type: dropdown
+    id: std_version
+    attributes:
+      label: C++ Standard
+      description: Which C++ standard are you targeting?
+      options:
+        - C++20
+        - C++23
+        - C++26
+    validations:
+      required: true
+
+  - type: input
+    id: mp_units_version
+    attributes:
+      label: mp-units Version
+      description: Which version of mp-units are you using?
+      placeholder: "e.g., 2.4.0, master, commit hash"
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: build_config
+    attributes:
+      label: Build Configuration
+      description: Select all that apply to your build configuration
+      options:
+        - label: Using Conan
+        - label: Using CMake directly
+        - label: Header-only mode
+        - label: C++ modules enabled
+        - label: Freestanding mode
+        - label: Debug build
+        - label: Release build
+
+  - type: textarea
+    id: additional_context
+    attributes:
+      label: Additional Context
+      description: Add any other context about the problem here (compiler flags, build system configuration, etc.)
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      description: Please confirm the following
+      options:
+        - label: I have read the documentation and checked existing issues
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: ❓ Ask Questions
+    url: https://github.com/mpusz/mp-units/discussions
+    about: For questions, help, discussions, and community support
+  - name: 📖 Documentation
+    url: https://mpusz.github.io/mp-units/
+    about: Comprehensive documentation with tutorials and examples

.github/ISSUE_TEMPLATE/documentation.yml

@@ -0,0 +1,71 @@
+name: 📚 Documentation Issue
+description: Report an issue with documentation or request documentation improvements
+title: "[Docs]: "
+labels: ["documentation", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Help us improve the mp-units documentation! Please describe the documentation issue or enhancement.
+
+  - type: dropdown
+    id: doc_type
+    attributes:
+      label: Documentation Type
+      description: What type of documentation issue is this?
+      options:
+        - Error/Inaccuracy in existing docs
+        - Missing documentation
+        - Unclear/Confusing explanation
+        - Broken link or formatting
+        - Example code issue
+        - API reference issue
+        - Tutorial improvement
+        - Installation instructions
+        - Migration guide
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: page_url
+    attributes:
+      label: Page URL
+      description: If applicable, provide the URL of the documentation page
+      placeholder: "https://mpusz.github.io/mp-units/..."
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Issue Description
+      description: Describe the documentation issue or improvement needed
+      placeholder: The documentation says... but it should say...
+    validations:
+      required: true
+
+  - type: textarea
+    id: location
+    attributes:
+      label: Location
+      description: Where in the documentation is this issue? (section, paragraph, code example, etc.)
+
+  - type: textarea
+    id: suggested_fix
+    attributes:
+      label: Suggested Fix
+      description: If you have suggestions for how to fix or improve this documentation, please share them
+
+  - type: textarea
+    id: additional_context
+    attributes:
+      label: Additional Context
+      description: Any other context about the documentation issue
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      description: Please confirm the following
+      options:
+        - label: I have checked that this documentation issue doesn't already exist
+          required: true