Skip to content

AGENTS.md

Latest commit

 

History

History
163 lines (130 loc) · 9.27 KB

AGENTS.md

File metadata and controls

163 lines (130 loc) · 9.27 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.
  • Never put tool-internal links into a commit message, PR description, JIRA comment or e-mail. This includes AI session and conversation URLs — Claude-Session:, https://claude.ai/code/session_…, https://chatgpt.com/c/… and any equivalent from another tool. Some assistants append one by default; that default does not apply to this project and must be overridden. The attribution line above is the whole of what belongs in a trailer block. Such a link is permanent once it reaches git history, means nothing to a reviewer, and may point at material that is not public — including work still under embargo per §6. Note that a force-push does not undo this: the superseded commit stays reachable by SHA.
  • 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.
  • Prose-only changes skip CI. A commit that only edits the text of existing documentation files ends its subject line with [skip ci], and the PR title carries it too: 
    THRIFT-9999: Clarify the TLS options in lib/cpp/README.md [skip ci]
    GitHub then runs none of the push and pull_request workflows for it, and AppVeyor skips the build.
    • Only the subject line works for both: AppVeyor ignores the rest of the message. A squash merge of several commits takes its subject from the PR title.
    • Not prose-only, so no marker: source code, comments and doc comments included; build, packaging and CI files; tests and test data (compiler/cpp/test/compiler/DocTest.md is a golden file, not documentation); adding, removing or renaming a file. EXTRA_DIST in the Makefile.am files lists documentation files by name: a removed or renamed one breaks the make dist job, and a new one needs an entry of its own, which no CI job asks for. Several package manifests name a README, too. When in doubt, leave the marker out.
    • The marker can skip CI for everything pushed along with it, so push a marked commit on its own. When a review round adds anything but prose, drop the marker as you amend.
    • GitHub also matches the marker when it is quoted. A commit that is not prose-only must not contain it, or GitHub's variants [ci skip], [no ci], [skip actions] and [actions skip], anywhere in its message. A squash message built from a PR description picks it up from the checklist in the PR template.
    • The marker also stops the tool-internal links check (§4) from running, so check the commit message (git log --format=%B) and the PR text yourself before pushing.

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
  • Prose-only change: [skip ci] ends the commit subject and the PR title; any other change: no such marker anywhere in the commit message
  • Tests added or updated
  • make style passes
  • AI authorship labelled with Co-Authored-By: / Generated-by: where applicable
  • No tool-internal or AI session URLs anywhere in the commit message or PR text
  • 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