Guidance for coding agents

This file is for AI coding agents (Claude Code, Cursor, Codex, Copilot, ...) working in this repository. Humans should read CONTRIBUTING.md.

Primary sources

• Official documentation: https://docs.fluentd.org/
  • Index for agents: https://docs.fluentd.org/llms.txt
  • Every page is also available as Markdown by appending .md to its URL, e.g. https://docs.fluentd.org/configuration/config-file.md
• Read the documentation before answering questions about configuration syntax or plugin parameters. Do not invent parameters; check the plugin's page or its config_param declarations in this repository.
• Configuration has two formats.
  • Classic: https://docs.fluentd.org/configuration/config-file.md
  • YAML: https://docs.fluentd.org/configuration/config-file-yaml.md

Repository layout

• lib/fluent/plugin/ – bundled plugins (in_*.rb, out_*.rb, filter_*.rb, parser_*.rb, formatter_*.rb, buf_*.rb, storage_*.rb, sd_*.rb, metrics_*.rb)
• lib/fluent/plugin_helper/ – plugin helpers
• lib/fluent/config/ – configuration parsers (classic and YAML)
• test/ – tests written with test-unit
• templates/new_gem/ – files generated by fluent-plugin-generate

Developing

• Install: bundle install
• Run all tests: bundle exec rake test
• Run one file: bundle exec ruby -Ilib -Itest test/plugin/test_in_tail.rb
• Plugin API reference: https://docs.fluentd.org/plugin-development/README.md
• Plugin helper reference: https://docs.fluentd.org/plugin-helper-overview/README.md
• Test helpers for plugins: https://docs.fluentd.org/plugin-development/plugin-test-code.md

Conventions

• Follow CONTRIBUTING.md. Commits need a DCO sign-off (git commit -s).
• Keep changes minimal and focused; do not reformat unrelated code.
• Add or update tests under test/ for behavior changes.
• Do not add runtime dependencies without discussion.
• Match the surrounding code style; there is no autoformatter to run. CI runs rubocop, but only the Security and Performance cops are enabled.
• Fluentd runs on Linux, macOS and Windows. CI tests ubuntu-latest, macos-latest, windows-latest and windows-11-arm. Assume your change must work on Windows.

Issues and pull requests

• Pull requests follow .github/PULL_REQUEST_TEMPLATE.md. Keep its headings, including Docs Changes and Release Note, and write Fixes #<n> when an issue exists.
• Blank issues are disabled. Use .github/ISSUE_TEMPLATE/bug_report.yml or .github/ISSUE_TEMPLATE/feature_request.yml and answer every required field.
• Questions belong in Discussions, not in issues.
• Note that gh pr create --body and gh issue create --body skip the template. Pass --template, or reproduce the template's sections in the body you supply.