# AGENTS.md – Core plugins subtree

These instructions apply to everything under `plugins/` (except `plugins/external`,
which vendors third-party code; do not modify it unless specifically requested).

## Build & bootstrap reminders
- **Efficient Build:** Use `make -j$(nproc) check TESTS=""` to incrementally build the core and all test dependencies. This is the primary build command.
- **Bootstrap/Configure:** Only run `./autogen.sh` and `./configure` if:
    1.  The `Makefile` is missing (first run).
    2.  You have modified `configure.ac`, `Makefile.am`, or `m4/` files.
    3.  You need to change build options (e.g., enabling a new module).
- **Testbench:** Keep the testbench enabled with `./configure --enable-testbench` (when configuring) so module-specific tests continue to compile.
- **Run Tests:** Execute the most relevant smoke/regression test directly (e.g., `./tests/imtcp-basic.sh`). Direct invocation keeps stdout/stderr visible. Use `make check` only when mirroring CI.

## Module-level agent guides
High-complexity modules benefit from their own `AGENTS.md` living directly
inside the module directory (for example `plugins/omelasticsearch/AGENTS.md`).
Use them to capture:

- A short overview plus links to user-facing docs.
- Build or dependency switches that only affect this module.
- Smoke/regression tests to run locally and any helper scripts to prepare
  external services.
- Common troubleshooting tips (log messages, stats counters, error files).
- Coordination notes when touching shared helpers or cross-module contracts.
- References to `MODULE_METADATA.yaml` and other metadata that must stay in
  sync.

Copy `plugins/MODULE_AGENTS_TEMPLATE.md` when creating a new module guide and
update it whenever workflows or dependencies change.

## Metadata required for every module
Each module directory (for example `plugins/omfile/`) should contain a
`MODULE_METADATA.yaml` file.  The file communicates ownership and expectations
for both humans and agents.

### Required keys
```yaml
support_status: core-supported | contributor-supported | stalled
maturity_level: fully-mature | mature | fresh | experimental | deprecated
primary_contact: "GitHub Discussions & Issues <https://github.com/rsyslog/rsyslog/discussions>"
last_reviewed: YYYY-MM-DD
```

#### Support status values
- `core-supported`: Maintained by the rsyslog core team.
- `contributor-supported`: Maintained primarily by a community contributor; the
  core team reviews but does not lead feature work.
- `stalled`: No active maintainer; use extra caution before changing behavior.

#### Maturity level values
- `fully-mature`: Long-standing module with well-established interfaces.
- `mature`: Stable but with medium deployment footprint or recent major changes.
- `fresh`: Recently added or lightly used; expect feedback-driven revisions.
- `experimental`: Works, but explicitly needs broader testing feedback before it
  can be considered stable.
- `deprecated`: Kept only for backward compatibility; avoid new feature work and
  document migration paths in user-facing docs.

### Optional keys
Add keys as needed to help future contributors:
- `build_dependencies`: List library or tool requirements (match configure
  options when possible).
- `runtime_dependencies`: Libraries or services the module needs at runtime.
- `ci_targets`: Names of CI jobs or scripts that exercise this module.
- `documentation`: Links into `doc/` or external references.
- `support_channels`: Overrides or supplements the default GitHub Discussions
  and Issues flow when a module has a bespoke support process.
- `notes`: Free-form guidance for reviewers and contributors.

Replace `primary_contact` with a specific maintainer string (e.g.
`"Full Name <email@example.com>"`) when a module has an active owner outside the
standard GitHub Discussions and Issues queue.

### Template
Copy `plugins/MODULE_METADATA_TEMPLATE.yaml` when creating or updating
module metadata.  Keep values accurate and review them whenever ownership or
support expectations change.

## Coding expectations
- Follow `MODULE_AUTHOR_CHECKLIST.md` for concurrency and documentation tasks.
- Update the module's top-of-file "Concurrency & Locking" comment when
  behavior changes.
- Update `doc/ai/module_map.yaml` if concurrency expectations change.
- When adding a new module, update `plugins/Makefile.am`, `configure.ac`, and
  provide tests under `tests/` to cover the new behavior.
- **Documentation**: Every new configuration parameter **must** be documented in
  `doc/source/reference/parameters/` and linked from the module's `.rst` file.
  Include a YAML example alongside the RainerScript example so operators using
  either format can understand the parameter.
- **Config format parity**: New parameters are automatically available in YAML
  (the YAML frontend uses the `nvlst` key name directly).  However, new
  *statement types* or *block types* require changes to `runtime/yamlconf.c` as
  well as the RainerScript grammar.  Consult the `rsyslog_config` skill before
  touching `grammar/` or adding a new top-level config construct.

## Testing expectations
- Prefer module-focused tests in `tests/` named after the module (e.g.
  `omxyz-basic.sh`).
- Ensure new tests run cleanly when invoked directly via `./tests/<script>.sh`.
  When reviewers request a CI reproduction, confirm the test also passes under
  `make check`.
- When a module requires external services (databases, message queues, etc.),
  document setup steps in the module metadata and reference any helper scripts
  placed under `tests/`.

## Documentation touchpoints
- Mention significant behavior or dependency changes in `doc/` (for example,
  module reference guides or changelog entries).
- Cross-link any new documentation from the appropriate `index.rst` so users
  can discover it easily.
