Add Conventions and Agent Instructions documentations

AGENTS.md

@@ -0,0 +1,13 @@
+# Agent Instructions
+
+## Conventions
+
+Follow [doc/conventions.md](doc/conventions.md).
+
+## Build & Test
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for build and test instructions.
+
+## Agent-Only Instructions
+
+Write short comments, with simple words and short sentences.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

CONTRIBUTING.md

@@ -1,40 +1,57 @@
-# Contributing
+# Contributing to the Datadog Apache Httpd Module
 
-## Fork, Clone, Branch and Create your PR
+## Conventions
+
+Follow [docs/conventions.md](doc/conventions.md).
+
+## Clone
 
 When cloning the repo, initialize the submodules you need. For a standard build:
 
 ```sh
 git submodule update --init deps/dd-trace-cpp deps/nginx-datadog
 ```
 
-The `deps/inject-browser-sdk` submodule is a private repo and is only required when building with `-DHTTPD_DATADOG_ENABLE_RUM=ON`. If you have access, use `--recursive` instead to pull it as well.
-
-### Rules
-- Follow the pattern of what you already see in the code.
-- Follow the coding style.
+The `deps/inject-browser-sdk` submodule is a private repository and is only required for RUM builds
+(with `-DHTTPD_DATADOG_ENABLE_RUM=ON`). If you have access, use `--recursive` instead to pull it as
+well:
 
-# Development
+```sh
+git submodule update --init --recursive
+```
 
 ## Prerequisites
 
-| Tool | Version | Notes |
-| ---- | ------- | ----- |
-| `clang` or `gcc` | 14+ or 11.4+ | |
-| `python` | 3.0+ | |
-| `cmake` | 3.12+ | |
+| Tool | Version |
+| ---- | ------- |
+| `clang` | 17+ |
+| `cmake` | 3.12+ |
+| `gcc` | 13.2+ |
+| `python` | 3.11+ |
 
 Once you got a valid Python installation, install all the dependencies with:
 
 ```sh
 pip install -r requirements.txt
 ```
 
+## Install Rust
+
+The RUM variant requires Rust to build:
+
+```sh
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+Relaunch your terminal (or do `source ~/.cargo/env`).
+
 ## Compiling
 
 ### Setup `httpd`
 
-In order to build the module you have to configure `httpd` with the [scripts/setup-httpd.py](./scripts/setup-httpd.py) script. Check what is the latest available version on [Apache website](https://httpd.apache.org), then:
+In order to build the module you have to configure `httpd` with the
+[scripts/setup-httpd.py](./scripts/setup-httpd.py) script. Check what is the latest available
+version on [Apache website](https://httpd.apache.org), then:
 
 ```sh
 export HTTPD_VERSION=2.4.66
@@ -43,19 +60,9 @@ cd httpd
 ./configure --with-included-apr --prefix=$(pwd)/httpd-build --enable-mpms-shared="all"
 ```
 
-### Install Rust
-
-The RUM variant requires Rust to build:
-
-```sh
-curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
-```
-
-Relaunch your terminal (or do `source ~/.cargo/env`).
-
 ### Build the Module
 
-CMake is our build system. If you are not familiar with CMake, read [the tutorial.](https://cmake.org/cmake/help/latest/guide/tutorial/index.html)
+CMake is our build system.
 
 Configure and compile all targets in release:
 
@@ -68,6 +75,38 @@ cmake --build build -j
 
 For now there are only [integration tests](./test/integration-test/).
 
-## How to Debug
+### Build Devcontainer Image
+
+```bash
+make ci-build          # Non-RUM CI build
+make test-integration  # RUM-enabled build and integration tests
+make dev-shell         # Interactive devcontainer shell
+```
+
+The devcontainer image is selected for the host architecture and includes the
+LLVM toolchain, httpd source, Rust, and uv.
+
+### Running Specific Tests Inside Docker
+
+```bash
+make dev-shell
+# Inside container:
+.devcontainer/run-integration-tests.sh \
+  scenarios/test_rum.py::test_rum_selective_disabling -m requires_rum
+```
+
+### Key Paths Inside the CI Image
+
+- `/httpd` — httpd source
+- `/httpd/httpd-build/bin/apachectl` — pre-built apachectl binary
+- `/sysroot/{arch}-none-linux-musl/Toolchain.cmake` — cross-compilation toolchain
+
+### Test Markers
+
+- `requires_rum` — tests needing RUM-enabled build (`-DHTTPD_DATADOG_ENABLE_RUM=ON`)
+- Tests without markers run against the standard build
+
+## CI
 
-Run with `-X`.
+GitLab CI status can be checked via `glab ci` on the [automated
+mirror](https://gitlab.ddbuild.io/DataDog/httpd-datadog).

README.md

@@ -1,17 +1,20 @@
-# Datadog Apache HTTPD Module
+# Datadog Apache Httpd Module
 
-This module adds distributed tracing to [Apache HTTP Server](https://httpd.apache.org/). Leveraging [Datadog's tracing library](https://github.com/DataDog/dd-trace-cpp/), it provides access to Datadog-specific functionality.
+This module adds distributed tracing to [Apache HTTP Server](https://httpd.apache.org/). Leveraging
+[Datadog's tracing library](https://github.com/DataDog/dd-trace-cpp/), it provides access to
+Datadog-specific functionality.
 
 ## Getting Started
 
-> [!IMPORTANT]
-> Only Apache HTTP Server 2.4.x is supported.
+> [!IMPORTANT] Only Apache HTTP Server 2.4.x is supported.
 >
-> For a detail understanding of our release cycle and Apache HTTPD support, read our [Release documentation](./doc/release.md).
+> For a detail understanding of our release cycle and Apache HTTPD support, read our [Release
+> documentation](./doc/release.md).
 
 ### Installation
 
-Download a gzipped tarball compatible with your version of Apache HTTPD, extract it to wherever `httpd` looks for modules and add the following line to the top of your configuration file:
+Download a gzipped tarball compatible with your version of Apache HTTPD, extract it to wherever
+`httpd` looks for modules and add the following line to the top of your configuration file:
 
 ```sh
 LoadModule datadog_module <MODULE_PATH>/mod_datadog.so
@@ -21,8 +24,15 @@ Then run `httpd -t <CONFIG_FILE>` to test the new configuration.
 
 ## Configuration
 
-Once the module is loaded, by default all requests are traced and sent to the Datadog Agent. To change the module default behaviour, check our [Configuration page.](./doc/configuration.md)
+Once the module is loaded, by default all requests are traced and sent to the Datadog Agent. To
+change the module default behaviour, check our [Configuration page.](./doc/configuration.md)
 
-## Development / Contribution
+## Contribution
 
-We welcome contributions. Before doing so, please read our [CONTRIBUTING.md](./CONTRIBUTING.md).
+See the [contributing guidelines](CONTRIBUTING.md) if you would like to contribute to the Datadog
+Apache Httpd Module.
+
+## Security
+
+If you discover a security vulnerablity in this softwa Datadog Apache Httpd Module, please refer to
+the [Security Policy](SECURITY.md).

SECURITY.md

@@ -1,17 +1,18 @@
-# Security Policy
-
-This document outlines the security policy for the Datadog HTTPD module and what to do if you discover a security vulnerability in the project.
-Most notably, please do not share the details in a public forum (such as in a discussion, issue, or pull request) but instead reach out to us with the details.
-This gives us an opportunity to release a fix for others to benefit from by the time details are made public.
+# Datadog Apache Httpd Module Security Policy
 
+This document outlines the security policy for the Datadog Httpd module and what to do if you
+discover a security vulnerability in the project. Most notably, please do not share the details in a
+public forum (such as in a discussion, issue, or pull request) but instead reach out to us with the
+details. This gives us an opportunity to release a fix for others to benefit from by the time
+details are made public.
 
 ## Supported Versions
 
-We accept vulnerability submissions for any currently maintained versions of HTTPD.
-
+We accept vulnerability submissions for the [currently maintained
+release](https://github.com/DataDog/httpd-datadog/releases).
 
 ## Reporting a Vulnerability
 
-If you discover a vulnerability please submit details to the following email address:
-
-* [security@datadoghq.com](mailto:security@datadoghq.com)
+If you discover a vulnerability in the Datadog Apache Httpd Module (or any Datadog product for that
+matter) please submit details to the [security@datadoghq.com](mailto:security@datadoghq.com) email
+address.

doc/conventions.md

@@ -0,0 +1,38 @@
+# Datadog Apache Httpd Module Conventions
+
+This document defines repository-wide conventions for `httpd-datadog`. Apply these conventions to
+all new and modified code.
+
+## C++ Version
+
+The project uses C++17.
+
+## Clean Code
+
+- Use meaningful variable and function names.
+- Do not use single-letter variable names.
+- Avoid abbreviations, unless very common and unambiguous.
+- Avoid obvious comments.
+- Prefer clearer variable and function names over explanatory comments.
+- Keep functions small and focused (<~ 20 lines when practical).
+- When practical, place caller functions before callees, so the code can be read from top to bottom.
+
+## C++ Code Style
+
+- Use modern C++ idioms.
+- Prefer explicit types. Use `auto` only for very long type names (>~ 50 characters).
+- Never use C-style casts.
+- Use raw pointers only when absolutely necessary.
+- Use C++17 nested namespace syntax.
+- Minimize the number of `#include` lines. Do not enforce the include-what-you-use rule.
+
+## Naming Conventions
+
+- class: `class TypeName;`
+- class member function: `.member_function();`
+- class public member: `int public_member;`
+- class private member: `int private_member_;`
+- free function: `free_function();`
+- function argument: `function(int func_arg);`
+- local variable: `int local_var;`
+- enumeration: `enum class Color { RED, GREEN, BLUE };`

doc/release.md

@@ -1,16 +1,19 @@
+# Release
+
 ## Versioning
-This module adheres to the principles of [Semantic Versioning (SemVer)](https://semver.org/). The version number is expressed as MAJOR.MINOR.PATCH, with the following guidelines:
+
+This module adheres to the principles of [Semantic Versioning (SemVer)](https://semver.org/). The
+version number is expressed as MAJOR.MINOR.PATCH, with the following guidelines:
 
 - MAJOR version: Increment for incompatible API changes.
 - MINOR version: Increment for backward-compatible feature additions.
 - PATCH version: Increment for backward-compatible bug fixes.
 
-We release at least one version per quarter. Nonetheless, we allow ourselves to release more if necessary.
-
 ## Compatibility Requirements
 
-Since this module is extending [Apache HTTP Server]() capabilities using the C interface, each versions are tied to a specific version of the webserver.
-Each module version will receive support for the specified HTTPD version range until the respective HTTPD versions reach their end-of-life.
+Since this module is extending Apache HTTP Server capabilities using the C interface, each versions
+are tied to a specific version of the webserver. Each module version will receive support for the
+specified HTTPD version range until the respective HTTPD versions reach their end-of-life.
 
 The following table outlines the compatibility between module versions and HTTPD versions:
 
@@ -19,5 +22,7 @@ The following table outlines the compatibility between module versions and HTTPD
 | 1.0.0                 | 2.4.0 - 2.4.54      | Current |
 
 ## Artifacts
-Release artifact are generated through a Continuous Integration pipeline. Our CI infrastructure ensures cross-platform compatibility by compiling shared libraries for both Linux `x86_64` and `arm64` architectures. 
-It generates shared libaries for each HTTPD version supported.
+
+Release artifact are generated through a Continuous Integration pipeline. Our CI infrastructure
+ensures cross-platform compatibility by compiling shared libraries for both Linux `x86_64` and
+`arm64` architectures. It generates shared libaries for each HTTPD version supported.