rsyslog/rsyslog
1
0
Fork 0
mirror of https://github.com/rsyslog/rsyslog.git synced 2026-06-19 17:32:56 +02:00
Code Issues Packages Projects Releases Wiki Activity
rsyslog/AGENTS.md
Rainer Gerhards f2998b50fe
ci: reduce PR fanout and cache configure results 
Why:
PR checks currently spend runner time on expensive lanes that cannot provide
additional signal for many narrow changes. This slows feedback and increases
CI cost while keeping branch protection tied to jobs that are often irrelevant.

Impact:
CI scheduling changes only; product code and test semantics are unchanged.

Before/After:
Before, most PRs fanned out broadly; after, CI uses scoped heavy lanes.

Technical Overview:
Add a pinned changed-files scope job that computes which families of checks
are relevant for a pull request and records the decision in the step summary.
Keep only the clang21 ndebug and gcc15 GNU23 debug compile lanes in the
required compile gate, and make that gate a mock success for PRs without C or
header changes. Move the other compile-only lanes to an extended compile job
that runs after the required gate and only for C/header changes.

Gate package, journal, service, analyzer, Kafka, arm64, and i386 jobs on the
scope outputs while keeping per-job changed-files checks as a safety belt.
Limit the Elasticsearch extra CI lane to runtime C/header changes and the
omelasticsearch plugin files only. Move imbeats to its own path-gated workflow
so it runs only for imbeats, omelasticsearch, runtime, test, or helper changes.
Move the Debian experimental package build out of PR CI and into a weekly or
manual workflow.

Remove redundant post-failure log gathering steps because the GitHub Actions UI
already exposes the logs. Enable opt-in Autoconf config.cache use for the
shared configure helper and static analyzer helper, and forward the cache
controls into dev containers. Add matching actions/cache steps with conservative
non-recursive keys so repeated PR runs can reuse configure probe results without
post-job hashing failures from generated test artifacts.

Document local workflow validation expectations for agents, including the
pinned zizmor check and avoiding direct template expansion in shell run blocks.

With the help of AI-Agents: Codex
2026-05-15 13:56:03 +02:00

6.2 KiB
Raw Blame History

AGENTS.md – rsyslog Repository Agent Guide

This file defines the high-level roadmap for AI assistants to understand and contribute to the rsyslog codebase. Technical workflows are now modularized into Skills.

Local Overlay

Before starting work in this repository, read AGENTS.local.md if it exists. That file contains machine- and workflow-specific instructions that are not duplicated here.

AI Agent Skills

To ensure consistency and high-quality contributions, AI agents SHOULD use the following standardized skills located in .agent/skills/:

Skill Purpose
rsyslog_build Environment setup and incremental parallel builds.
rsyslog_test Standardized validation and debugging via diag.sh.
rsyslog_local_container_testing CI-style local dev-container validation, analyzer-first flow, service-skip checks, and clean-tree rules.
rsyslog_pr_babysitting Post-push PR monitoring, including CI failures, reruns, and unresolved review-thread checks.
rsyslog_doc Structured, RAG-optimized documentation and metadata.
rsyslog_doc_dist Syncing documentation files in doc/Makefile.am.
rsyslog_module Technical patterns for concurrency and module authoring.
rsyslog_config Dual-frontend config architecture (RainerScript + YAML) and parity rules.
rsyslog_issue_triage GitHub issue backlog triage, clustering, closure comments, and local evidence boards.
rsyslog_commit Compliant commit messages and branching policies.

Agent Quick Start: The "Happy Path"

Follow these three steps for a typical development task:

  1. Build: Use the rsyslog_build skill to set up and compile.
  2. Validate: Use the rsyslog_test skill to run relevant shell tests.
  3. Commit: Use the rsyslog_commit skill to format code and draft your message.
    • Tip: You do NOT need to re-run your build/test cycle after formatting if you already validated the code immediately before.

Repository Overview

  • Primary Language: C (v8 worker model)
  • Architecture: Microkernel core (runtime/) + Loadable Plugins (plugins/)
  • Metadata: Every module directory contains MODULE_METADATA.yaml.
  • Knowledge Base: doc/ai/ contains canonical patterns for RAG ingestion.
  • Security Triage: doc/ai/security_triage_rubric.md defines how AI agents must distinguish confirmed issues from potential issues, hardening, and invalid findings before using security severity or CWE language.

Container Images

  • Runtime container definitions live in packaging/docker/rsyslog.
  • Local GitHub Actions-style validation commands for the Ubuntu 26.04 dev container, -j80 check runs, clang static analyzer, disabled external services, and Docker storage cleanup are documented in the rsyslog_local_container_testing skill. AI agents should use that skill when running or planning this validation.
  • The container Makefile default version must stay clearly non-release. Use explicit VERSION=... values for release-like local rehearsals and for any publish automation.
  • Release-tagged container images are downstream of package publishing. AI agents must not add or use release container flows that bypass the Adiscon PPA readiness check.
  • Manual release flows use two fixed channels: stable maps 8.yymm.0 to 20yy-mm via ppa:adiscon/v8-stable, and daily-stable uses ppa:adiscon/daily-stable with the fixed tag daily-stable.
  • AI agents must not introduce release-looking fallback tags such as 2026-03 as the default local container build version.

Context Discovery (Subtree Guides)

Each major subtree contains a specialized AGENTS.md that points to area-specific context and requirements:

Test Structure Rule

  • For this recursive Automake tree, keep tests/ as the single recursive test-owning subtree.
  • New and changed tests must include inline intent documentation that says what behavior, regression, or invariant they test. If an existing test lacks that context, add it while touching the test.
  • It is fine to organize sources under tests/unit/, tests/helpers/, or similar folders, but register and run those tests from tests/Makefile.am.
  • Do not introduce additional recursive tests/.../Makefile.am test harnesses. Top-level make check TESTS=... propagates into every subdirectory, and multiple test-owning subdirs make targeted selection fragile.

GitHub Actions Validation

  • When editing files under .github/workflows/, validate locally with actionlint .github/workflows/<file>.yml and the pinned zizmor version: python3 -m venv .zizmor-venv && .zizmor-venv/bin/python -m pip install -r .github/requirements-zizmor.txt && .zizmor-venv/bin/zizmor --strict-collection .github/workflows.
  • Avoid direct ${{ ... }} template expansion inside shell run: scripts. Pass expression values through env: variables and expand those variables in the shell script instead.

Agent Chat Keywords

  • SETUP: Triggers the rsyslog_build setup workflow.
  • BUILD: Triggers the rsyslog_build incremental build workflow.
  • TEST: Triggers the rsyslog_test validation workflow.
  • SUMMARIZE: Generates PR and commit summaries using rsyslog_commit templates.
  • FINISH: Final review of code and style before conclusion.

For human-facing guidelines, see CONTRIBUTING.md and DEVELOPING.md.