docs: add comprehensive AGENTS.md documentation for all products #3714
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Add ppg/AGENTS.md: PostgreSQL pipelines (69 files, 20+ extensions, PG 14-18) - Add pdmdb/AGENTS.md: Distribution MongoDB testing - Add pdps/AGENTS.md: Distribution Percona Server testing - Add pdpxc/AGENTS.md: Distribution XtraDB Cluster testing - Add proxysql/AGENTS.md: ProxySQL 2.x pipelines (most active product) - Add percona-telemetry-agent/AGENTS.md: Telemetry agent packaging - Add prel/AGENTS.md: Percona Release tool pipelines - Add pcsm/AGENTS.md: Cloud Service Manager (formerly PLM) - Add pmm/v3/AGENTS.md: Nested PMM v3 documentation (HA/EKS, AMI/OVF) - Update pmm/AGENTS.md: Add v3 nested reference - Update IaC/AGENTS.md: Clarify no CDK directory, document Lambda/CloudFormation - Update root AGENTS.md: Add all product references, navigation guide Follows 2025 AGENTS.md best practices with progressive disclosure, auto-discovery pattern, and comprehensive git history enrichment. All files enriched with: - Git history contributor analysis - Version matrices and platform support - Validation commands and workflows - Jenkins CLI integration examples - Code owner references
- Remove Hetzner-specific AGENTS.md files (pmm/, pmm/v3/, ppg/, pcsm/, IaC/) - these have Hetzner-specific content (ARM64, no EKS/OpenShift) - Add master-specific AGENTS.md files for components without Hetzner work: - ps/, pxc/, pxb/ - MySQL family products - cloud/ - OpenShift/EKS operator testing (master-only) - pbm/, psmdb/ - MongoDB family - vars/ - Shared library documentation Components documented in master branch: - ps/, pxc/, pxb/ - MySQL products - psmdb/, pbm/ - MongoDB products - cloud/ - K8s operators with EKS/OpenShift - vars/ - Shared library (lib@master) - pdmdb/, pdps/, pdpxc/ - Distributions - proxysql/, prel/, percona-telemetry-agent/ Hetzner-specific components (see hetzner branch): - pmm/, pmm/v3/ - PMM without OpenShift - ppg/ - PostgreSQL with ARM64 - pcsm/ - Cloud Service Manager with ARM64 - IaC/ - Hetzner Cloud infrastructure
- Add compact Jenkins CLI section with quick commands - Add curl API equivalents (URL-encoded brackets) - Add job patterns for each product directory - Reference root AGENTS.md for auth setup in subdirectories
Each AGENTS.md now has a dedicated # Jenkins section that groups: - Instance URL - CLI commands - API/curl commands - Job patterns - Credentials
- Fix P0 issues: broken refs, wrong paths (cloud/aws/ -> cloud/aws-functions/), helper count (~70 -> ~100) - Add TL;DR sections with 4-line summaries to all 14 files - Add Quick Reference tables (Jenkins instance, URL, job patterns, credentials) - Restructure Key Files sections with actual file paths in tables - Add Common Pitfalls and PR Review Checklist sections - Add Change Impact matrices for major products - Add Molecule testing sections where applicable - Add AWS Infrastructure section to root (regions, services, costs) - Enhance vars/AGENTS.md with library usage stats by product
Member
|
@nogueiraanderson I wonder what would that look like for pmm? :) |
Add Jenkins-verified job architecture data: - Node metrics table with build counts, tiers, fan-in/out, risk levels - 56 explicit edges from build job: calls - Upstream trigger chain (auto-cascade relationships) - Stability tiers (CRITICAL/HIGH based on caller count) - Job alias mapping (code references to actual Jenkins names) Data verified via jenkins CLI against pmm.cd.percona.com
- Fix jenkins CLI flag: --yaml to -f yaml (correct syntax) - Add percona-telemetry-agent to root AGENTS.md index - Fix pmm/AGENTS.md reference in cloud/AGENTS.md
- Add banner pointing to active hetzner branch - Update job patterns to hetzner-* prefix - Note active versions (6.0, 7.0, 8.0) - Update infrastructure from AWS to Hetzner
Add comprehensive documentation matching PMM format: - Job dependency graph with node metrics and explicit edges - Stability tiers (CRITICAL/HIGH) for downstream contracts - Complete credentials mapping with types and usage - Agent/node labels with usage counts - Git archaeology: churn hotspots, top contributors - Related GitHub repositories section - Cross-references to PMM and cloud AGENTS.md Increases from 116 to 375 lines with actionable context for AI agents.
Add comprehensive documentation matching PMM/PS format: - Operator-Platform coverage matrix (pxco, psmdbo, pgo, pso) - Cost tiers by platform ($50-300/day) - Weekly scheduler job dependencies with cron schedules - Complete credentials mapping (AWS, GCP, Azure, DO, Docker) - Orphaned resource cleanup documentation (Python + Go) - Agent/node labels with Hetzner conditional support - Git archaeology: churn hotspots, top contributors - Related GitHub repositories for all 4 operators Increases from 140 to 441 lines with actionable context for AI agents.
- Remove "PR Review Checklist" sections from all enhanced AGENTS.md files (pxb, pbm, proxysql, pdpxc, pdmdb, pxc, cloud) - Fix invalid GitHub repository references: - pdpxc: Percona-QA/pxc-testing → Percona-QA/pxc-qa - pdps: Percona-QA/ps-testing → Percona-QA/package-testing - Verify all GitHub repos are valid and up to date via gh CLI
- Add fanout metrics to job dependency graphs (pdpxc, pdmdb, pdps) - Update Jenkins CLI references with accurate job names and rg usage - Add JJB YAML documentation to root AGENTS.md - Include history commands for better job tracking - Standardize CLI examples across all AGENTS.md files
- pxb: Platform modernization, PRO builds, Ubuntu Noble compat - pbm: Docker nightly, multi-arch, GCS SDK migration - proxysql: ProxySQL 3.x support, binary testing fix - Root: Product dependency chains by family
Dependency direction fixes: - PXB: Clarify "uses for backups/SST" not "depends on" - PS/PXC: Reciprocal references now consistent Missing cross-references added: - ProxySQL <-> PDPS, PDPXC - Cloud <-> PDPXC, PDMDB, PS, PSMDB - PMM Related section added (cloud, ps, pxc, psmdb) - PXB <-> PDPS, PDPXC Section title standardization: - All files now use "## Related" (was "## Related AGENTS.md Files") ProxySQL dual-instance clarification: - Updated Quick Reference to show pxc (QA jobs) + ps80 (package testing)
New files: - IaC/AGENTS.md: Lambda functions, CF stacks, Jenkins instances - resources/AGENTS.md: Python helpers, cleanup scripts Enhanced files: - vars/AGENTS.md: Molecule patterns, platform matrix, OpenShift helpers - Root AGENTS.md: Hetzner migration, PRO builds, JJB, platform adoption - cloud/pmm: Add IaC/resources cross-refs Cross-cutting topics now centralized: - Lambda cleanup (EC2/Volume/OpenShift with protection patterns) - Molecule credential matrix (6 families, partial redaction) - Hetzner migration status (PSMDB/PBM complete, PXC partial) - PRO build infrastructure (5 products, 2 cred families) - JJB script-path mapping patterns - Platform adoption timeline (RHEL 10, Noble, Debian 13, AL2023)
nogueiraanderson
force-pushed
the
feat/agents-md-master
branch
from
8bd98b8 to
13dee1e
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
# Jenkinssections~/bin/jenkins) and curl API equivalentsWhy
AGENTS.md is an emerging standard (20,000+ repos) that serves as "README for AI agents." It helps AI coding assistants understand project structure, patterns, and boundaries.
Changes
14 files updated: root, cloud, pbm, pdmdb, pdps, pdpxc, percona-telemetry-agent, prel, proxysql, ps, psmdb, pxb, pxc, vars
Each
# Jenkinssection includes: Instance/URL, CLI commands, API/curl, job patterns, credentials.