docs: add inline SBDL declarations to Gherkin feature files

Copilot · rjaegers · Copilot · commit f9942b25b44f · 2026-02-27T16:45:39.000Z
Co-authored-by: rjaegers &lt;45816308+rjaegers@users.noreply.github.com&gt;
diff --git a/test/cpp/features/compatibility.feature b/test/cpp/features/compatibility.feature
@@ -1,17 +1,20 @@
 Feature: Compatibility
+  # @sbdl compatibility is aspect { description is "As a software craftsperson, I want my development environment to be compatible with commonly used tools and systems." }
 
   As a software craftsperson,
   to ensure that my development environment works well with a variety of tools and systems,
   I want my development environment to be compatible with commonly used tools and systems.
 
   @REQ-COMPAT-0001
   Rule: Open Container Initiative (OCI) Image Specification
+    # @sbdl req-compat-0001 is requirement { description is "amp-devcontainer images *SHALL* be compatible with the [OCI image specification](https://github.com/opencontainers/image-spec/blob/main/spec.md)" aspect is compatibility }
     amp-devcontainer images *SHALL* be compatible with the [OCI image specification](https://github.com/opencontainers/image-spec/blob/main/spec.md)
 
     To guarantee compatibility with container runtimes and container- and image tooling; amp-devcontainer should be compatible with the OCI image specification.
 
   @REQ-COMPAT-0002
   Rule: Host architecture
+    # @sbdl req-compat-0002 is requirement { description is "amp-devcontainer *SHALL* be compatible with both the x86-64 (AMD64) *and* AArch64 (ARM64) host architectures." aspect is compatibility }
     amp-devcontainer *SHALL* be compatible with both the x86-64 (AMD64) *and* AArch64 (ARM64) host architectures.
 
     Supporting both x86-64 and AArch64 has several advantages:
@@ -21,6 +24,7 @@ Feature: Compatibility
 
   @REQ-COMPAT-0003
   Rule: Integrated Development Environment (IDE)
+    # @sbdl req-compat-0003 is requirement { description is "amp-devcontainer *SHOULD* be compatible with [VS Code](https://code.visualstudio.com/) *and* [GitHub Codespaces](https://github.com/features/codespaces)." aspect is compatibility }
     amp-devcontainer *SHOULD* be compatible with [VS Code](https://code.visualstudio.com/) *and* [GitHub Codespaces](https://github.com/features/codespaces).
 
     It should be possible to use amp-devcontainer and all of its features in both VS Code and GitHub Codespaces with minimal effort.
@@ -29,6 +33,7 @@ Feature: Compatibility
 
   @REQ-COMPAT-0004
   Rule: GitHub Actions
+    # @sbdl req-compat-0004 is requirement { description is "amp-devcontainer *SHOULD* support seamless integration with [GitHub Actions](https://github.com/features/actions) without additional configuration." aspect is compatibility }
     amp-devcontainer *SHOULD* support seamless integration with [GitHub Actions](https://github.com/features/actions) without additional configuration.
 
     Seamless integration with GitHub Actions allows users to easily incorporate amp-devcontainer into their ci/cd workflows.
diff --git a/test/cpp/features/compilation.feature b/test/cpp/features/compilation.feature
@@ -1,11 +1,13 @@
 Feature: Compilation
+  # @sbdl compilation is aspect { description is "As a software developer, source code needs to be compiled into working software." }
 
   As a software developer,
   to generate a working product, when using compiled languages,
   source code needs to be compiled into working software.
 
   @REQ-COMP-0001
   Rule: Compile for container host architecture and operating system
+    # @sbdl req-comp-0001 is requirement { description is "amp-devcontainer *SHALL* be able to compile valid source code into a working executable targeting the container host architecture and operating system." aspect is compilation }
     amp-devcontainer *SHALL* be able to compile valid source code into a working executable targeting the container host architecture and operating system.
 
     Compiling valid source code into working software, able to run on the container host architecture and operating system,
@@ -17,13 +19,15 @@ Feature: Compilation
 
     @flavor:cpp
     Scenario: Compile valid source code into working software targeting the container host architecture
+      # @sbdl compile-valid-source-code-into-working-software-targeting-the-container-host-architecture is test { description is "Compile valid source code into working software targeting the container host architecture" requirement is req-comp-0001 }
       Given build configuration "gcc" is selected
       And build preset "gcc" is selected
       When the selected target is built
       Then the output should contain "Build finished with exit code 0"
 
   @REQ-COMP-0002
   Rule: Compile for ARM Cortex target architecture
+    # @sbdl req-comp-0002 is requirement { description is "amp-devcontainer *SHOULD* be able to compile valid source-code into a working ELF executable targeting the ARM Cortex architecture." aspect is compilation }
     amp-devcontainer *SHOULD* be able to compile valid source-code into a working ELF executable targeting the ARM Cortex architecture.
 
     Compiling valid source-code into working ELF executables, able to run on the ARM Cortex architecture,
@@ -32,6 +36,7 @@ Feature: Compilation
 
   @REQ-COMP-0003
   Rule: Compile for Microsoft® Windows operating system
+    # @sbdl req-comp-0003 is requirement { description is "amp-devcontainer *SHOULD* be able to compile valid source-code into a working executable targeting the Microsoft® Windows operating system." aspect is compilation }
     amp-devcontainer *SHOULD* be able to compile valid source-code into a working executable targeting the Microsoft® Windows operating system.
 
     Compiling valid source-code into working executables, able to run on the Microsoft® Windows operating system, can be necessary in several scenarios e.g.
@@ -41,6 +46,7 @@ Feature: Compilation
 
   @REQ-COMP-0004
   Rule: Compilation cache
+    # @sbdl req-comp-0004 is requirement { description is "amp-devcontainer *MAY* be able to cache the results of a compilation to speed-up subsequent compilations." aspect is compilation }
     amp-devcontainer *MAY* be able to cache the results of a compilation to speed-up subsequent compilations.
 
     Maintaining a compilation cache can be useful in both local and ci development scenarios. A compilation cache can provide benefits like:
diff --git a/test/cpp/features/debugging.feature b/test/cpp/features/debugging.feature
@@ -1,11 +1,13 @@
 Feature: Debugging
+  # @sbdl debugging is aspect { description is "As a software craftsperson, I want to be able to debug my source code within the development environment." }
 
   As a software craftsperson,
   to efficiently identify and resolve issues in my code,
   I want to be able to debug my source code within the development environment.
 
   @REQ-DBG-0001
   Rule: Debugging support
+    # @sbdl req-dbg-0001 is requirement { description is "amp-devcontainer *SHALL* provide debugging support for the primary programming language(s) used within the container." aspect is debugging }
     amp-devcontainer *SHALL* provide debugging support for the primary programming language(s) used within the container.
 
     Providing debugging support within the development environment enhances the developer experience and productivity.
@@ -15,6 +17,7 @@ Feature: Debugging
 
   @REQ-DBG-0002
   Rule: Upload firmware to micro-controller
+    # @sbdl req-dbg-0002 is requirement { description is "amp-devcontainer *MAY* provide tools to upload compiled firmware to a connected micro-controller." aspect is debugging }
     amp-devcontainer *MAY* provide tools to upload compiled firmware to a connected micro-controller.
 
     Providing tools to upload compiled firmware to a connected micro-controller enhances the development workflow for embedded systems.
diff --git a/test/cpp/features/maintainability.feature b/test/cpp/features/maintainability.feature
@@ -1,11 +1,13 @@
 Feature: Maintainability
+  # @sbdl maintainability is aspect { description is "As a software craftsperson, I want my development environment to be maintainable over time." }
 
   As a software craftsperson,
   to ensure that I have access to a stable and reliable development environment,
   I want my development environment to be maintainable over time.
 
   @REQ-MAINT-0001
   Rule: Tool and dependency updates
+    # @sbdl req-maint-0001 is requirement { description is "amp-devcontainer *SHOULD* contain up-to-date tools and dependencies." aspect is maintainability }
     amp-devcontainer *SHOULD* contain up-to-date tools and dependencies.
 
     Keeping tools and dependencies up-to-date helps ensure that the development environment remains secure, stable, and compatible with the latest technologies.
@@ -14,6 +16,7 @@ Feature: Maintainability
 
   @REQ-MAINT-0002
   Rule: Automatic updates
+    # @sbdl req-maint-0002 is requirement { description is "amp-devcontainer *SHOULD* provide support for automatic updates when consumed as a dependency." aspect is maintainability }
     amp-devcontainer *SHOULD* provide support for automatic updates when consumed as a dependency.
 
     Providing support for automatic updates when amp-devcontainer is consumed as a dependency helps ensure that users always have access to the latest features, bug fixes, and security patches.
@@ -22,13 +25,15 @@ Feature: Maintainability
 
   @REQ-MAINT-0003
   Rule: Re-usable build system
+    # @sbdl req-maint-0003 is requirement { description is "amp-devcontainer *SHOULD* provide re-usable building blocks to enable building, publishing and testing derived containers." aspect is maintainability }
     amp-devcontainer *SHOULD* provide re-usable building blocks to enable building, publishing and testing derived containers.
 
     Providing re-usable building blocks for building, publishing and testing derived containers reduces duplication, and ensures consistent application of practices.
     Derived containers (i.e. containers using amp-devcontainer as a base for further extension) should be able to build, push and test in the same way that amp-devcontainer does, without the need to duplicate the build system.
 
   @REQ-MAINT-0004
   Rule: Architectural decisions
+    # @sbdl req-maint-0004 is requirement { description is "amp-devcontainer *SHOULD* document its architectural decisions." aspect is maintainability }
     amp-devcontainer *SHOULD* document its architectural decisions.
 
     Documenting architectural decisions helps provide context and rationale for the design choices made in the development environment.
@@ -37,6 +42,7 @@ Feature: Maintainability
 
   @REQ-MAINT-0005
   Rule: Container image size
+    # @sbdl req-maint-0005 is requirement { description is "amp-devcontainer *SHOULD* aim to keep its container image size as small as possible without compromising functionality." aspect is maintainability }
     amp-devcontainer *SHOULD* aim to keep its container image size as small as possible without compromising functionality.
 
     Keeping the container image size small helps improve performance, reduce resource consumption, and minimize the time required to download and deploy the development environment.
diff --git a/test/cpp/features/security.feature b/test/cpp/features/security.feature
@@ -1,11 +1,13 @@
 Feature: Security
+  # @sbdl security is aspect { description is "As a security engineer, I want to have controls in place to identify and mitigate supply-chain vulnerabilities." }
 
   As a security engineer and security conscious developer,
   to have control over the security posture of my development environment,
   I want to have controls in place to identify and mitigate supply-chain vulnerabilities.
 
   @REQ-SEC-0001
   Rule: Build provenance
+    # @sbdl req-sec-0001 is requirement { description is "amp-devcontainer *SHALL* include build provenance as specified in [SLSA v1.0 Build L3](https://slsa.dev/spec/v1.0/levels)." aspect is security }
     amp-devcontainer *SHALL* include build provenance as specified in [SLSA v1.0 Build L3](https://slsa.dev/spec/v1.0/levels).
 
     Including provenance gives confidence that the container images haven't been tampered with and can be securely traced back to its source code.
@@ -15,6 +17,7 @@ Feature: Security
 
   @REQ-SEC-0002
   Rule: Signing
+    # @sbdl req-sec-0002 is requirement { description is "amp-devcontainer *SHALL* cryptographically sign its released container images." aspect is security }
     amp-devcontainer *SHALL* cryptographically sign its released container images.
 
     Cryptographically signing released container images provides integrity and authenticity guarantees.
@@ -23,6 +26,7 @@ Feature: Security
 
   @REQ-SEC-0003
   Rule: Software Bill of Materials (SBOM)
+    # @sbdl req-sec-0003 is requirement { description is "amp-devcontainer *SHOULD* provide a Software Bill of Materials (SBOM) for its released container images." aspect is security }
     amp-devcontainer *SHOULD* provide a Software Bill of Materials (SBOM) for its released container images.
 
     Providing a Software Bill of Materials (SBOM) enables consumers to identify and manage security risks associated with the software components included in the container images.
diff --git a/test/cpp/features/static-dynamic-analysis.feature b/test/cpp/features/static-dynamic-analysis.feature
@@ -1,11 +1,13 @@
 Feature: Static and dynamic analysis
+  # @sbdl static-and-dynamic-analysis is aspect { description is "As a software craftsperson, I want my source code to be statically and dynamically analyzed." }
 
   As a software craftsperson,
   to maintain consistent, high-quality and bug-free code,
   I want my source code to be statically and dynamically analyzed.
 
   @REQ-SDA-0001
   Rule: Code formatting
+    # @sbdl req-sda-0001 is requirement { description is "amp-devcontainer *MAY* provide code formatting tools for the primary programming language(s) used within the container." aspect is static-and-dynamic-analysis }
     amp-devcontainer *MAY* provide code formatting tools for the primary programming language(s) used within the container.
 
     Providing code formatting tools helps maintain a consistent coding style across the codebase, improving readability and reducing friction during code reviews.
@@ -14,13 +16,15 @@ Feature: Static and dynamic analysis
 
   @flavor:cpp @fixme
   Scenario: Format source code according to a formatting style
+    # @sbdl format-source-code-according-to-a-formatting-style is test { description is "Format source code according to a formatting style" requirement is req-sda-0001 }
     Given the file "clang-tools/unformatted.cpp" is opened in the editor
     When the active document is formatted
     And the active document is saved
     Then the contents of "clang-tools/unformatted.cpp" should match the contents of "clang-tools/formatted.cpp"
 
   @REQ-SDA-0002
   Rule: Static analysis
+    # @sbdl req-sda-0002 is requirement { description is "amp-devcontainer *MAY* provide static analysis tools for the primary programming language(s) used within the container." aspect is static-and-dynamic-analysis }
     amp-devcontainer *MAY* provide static analysis tools for the primary programming language(s) used within the container.
 
     Providing static analysis tools helps identify potential issues in the code before it is executed, improving code quality and reducing the likelihood of runtime errors.
@@ -29,6 +33,7 @@ Feature: Static and dynamic analysis
 
   @REQ-SDA-0003
   Rule: Coverage analysis
+    # @sbdl req-sda-0003 is requirement { description is "amp-devcontainer *SHOULD* provide code coverage analysis tools for the primary programming language(s) used within the container." aspect is static-and-dynamic-analysis }
     amp-devcontainer *SHOULD* provide code coverage analysis tools for the primary programming language(s) used within the container.
 
     Providing code coverage analysis tools helps assess the effectiveness of the existing test suite by measuring how much of the code is exercised by the tests.
@@ -37,6 +42,7 @@ Feature: Static and dynamic analysis
 
   @REQ-SDA-0004
   Rule: Mutation testing
+    # @sbdl req-sda-0004 is requirement { description is "amp-devcontainer *MAY* provide mutation testing tools for the primary programming language(s) used within the container." aspect is static-and-dynamic-analysis }
     amp-devcontainer *MAY* provide mutation testing tools for the primary programming language(s) used within the container.
 
     Providing mutation testing tools helps assess the effectiveness of the existing test suite by introducing small changes (mutations) to the code and checking if the tests can detect these changes.
@@ -45,6 +51,7 @@ Feature: Static and dynamic analysis
 
   @REQ-SDA-0005
   Rule: Fuzz testing
+    # @sbdl req-sda-0005 is requirement { description is "amp-devcontainer *MAY* provide fuzz testing tools for the primary programming language(s) used within the container." aspect is static-and-dynamic-analysis }
     amp-devcontainer *MAY* provide fuzz testing tools for the primary programming language(s) used within the container.
 
     Providing fuzz testing tools helps identify potential security vulnerabilities and robustness issues in the code by automatically generating and executing a large number of random inputs.
