Skip to content

AGENTS.md

Latest commit

 

History

History
130 lines (97 loc) · 6.62 KB

AGENTS.md

File metadata and controls

130 lines (97 loc) · 6.62 KB
Raw

Apache Thrift — AI Contribution Guidelines

This file governs AI-assisted work on the Apache Thrift codebase. It supplements but does not replace CONTRIBUTING.md.

1. ASF Legal Compliance (Third-Party Code)

Apache Thrift is an Apache Software Foundation (ASF) project released under the Apache License 2.0. The AI must actively enforce and monitor ASF licensing policy:

  • Proactively flag conflicts: Before introducing any dependency, snippet, or code derived from an external source, verify its license is compatible with Apache 2.0. Incompatible licenses include (non-exhaustive): GPL, AGPL, SSPL, BUSL, CC-BY-NC. Compatible examples: MIT, BSD-2/3, Apache 2.0, ISC, MPL 2.0 (with caveats).
  • Category X / Category A: Follow the ASF Third-Party Licensing Policy. Category A licenses may be included; Category X licenses must never be introduced.
  • Update LICENSE and NOTICE: When adding third-party code or binaries that require attribution, add the appropriate notices to LICENSE and/or NOTICE following the ASF guide on licenses and notices. If in doubt whether an entry is required, add it and flag it in the PR description for committer review.
  • Generative AI output: The ASF Generative Tooling Guidance applies. Be aware that AI-generated code may unintentionally reproduce copyrighted material. Flag any non-trivial generated blocks in commit messages or PR descriptions.

2. Issue Tracking

Type Tracker Notes
Significant changes Apache JIRA — THRIFT project Required for all non-trivial PRs
Minor / quick fixes GitHub Issues Typos, trivial compiler warnings, etc.

JIRA integration with GitHub: Including a JIRA ticket identifier at the start of a PR title automatically creates a link from JIRA to the PR.

  • PR title format: THRIFT-9999: Short description of the change
  • Commit message format (required for code changes): 
    THRIFT-9999: Short description of the change
Client: cpp,py,java   (comma-separated list of affected languages)

Example: THRIFT-5929 → PR #3350.

3. Pull Request Requirements

Follow CONTRIBUTING.md in full. Key points:

  • One commit per issue (squash before submitting).
  • All significant changes need a JIRA ticket.
  • Provide tests for every submitted change.
  • Verify coding standards: make style.
  • Branch name convention: use the JIRA ticket ID, e.g. THRIFT-9999.
  • PRs go from your fork branch → apache:master.

4. AI-Generated Contributions

Per CONTRIBUTING.md § AI generated content and the ASF Generative Tooling Guidance:

  • Always label AI-assisted commits and PRs. Use one or both of: 
    Co-Authored-By: <AI tool name and version>
Generated-by: <AI tool name and version>
    Example: 
    THRIFT-9999: Fix connection timeout handling in Go client
Client: go

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
  • Apply this label even when AI only generated a portion of the change.
  • The human author remains responsible for reviewing, testing, and standing behind all submitted code.

5. Language-Specific Rules (/lib, /test, /tutorial)

  • This file remains valid in all cases and must be used in addition to any additional language-specific rules.
  • If a target-language directory under /lib/<lang>/ contains its own CLAUDE.md or AGENTS.md, those rules apply to all work in that language directory.
  • Those language-specific rules extend by implication to the corresponding language code under /test/ and /tutorial/.
  • If /test/ or /tutorial/ themselves contain a CLAUDE.md/AGENTS.md for a given language, combine the rules: the file closer to the code (i.e., in the same directory) takes precedence on any conflict.

6. Security Work

When assisting with security-sensitive changes (transport size limits, TLS configuration, authentication, serialization bounds, or anything flagged by the project's security team):

  • Never describe the change as a security fix in public-facing text — commit messages, PR titles, PR descriptions, or inline comments. Use neutral functional language: "add a configurable frame-size limit" rather than "fix DoS vulnerability". Vulnerability details travel through the private ASF channel (security@apache.org); AI tooling must not short-circuit that process.
  • Before proposing mitigations or defaults, consult doc/thrift-threat-model.md for the project's documented attack surface, trust boundaries, and per-binding security properties.
  • External reporters and AI reviewers alike should follow the instructions in SECURITY.md for responsible disclosure.
  • When asserting a security claim or identifying which component a bug affects, verify reachability/exploitability empirically against the specific released version before stating it as fact.

7. Code Changes, Git & PR Workflow

  • When fixing a bug or addressing an issue, scope the change to ONLY that issue. Do not touch CHANGES.md, version files, or unrelated entries unless explicitly asked.
  • Ship bug fixes as standalone pull requests by default. Do not commit directly to master or mix fixes into existing/unrelated work unless told otherwise.
  • Follow a strict test-first workflow: write or update tests demonstrating the bug BEFORE applying the fix, and inspect any generated code before changing it.

8. Quick Reference Checklist (before opening a PR)

  • License of any new dependency checked against ASF Category A/X list
  • LICENSE and/or NOTICE updated if third-party attribution is required
  • JIRA ticket exists (unless truly trivial)
  • PR title starts with THRIFT-NNNN: (if ticket exists)
  • Commit message includes affected Client: languages
  • Single squashed commit
  • Tests added or updated
  • make style passes
  • AI authorship labelled with Co-Authored-By: / Generated-by: where applicable
  • Security-sensitive changes use neutral commit/PR language (no public vulnerability details)
  • Changes touching transport limits / TLS / auth cross-checked against doc/thrift-threat-model.md