Skip to content

Latest commit

 

History

History
159 lines (107 loc) · 7.13 KB

AGENTS.md

File metadata and controls

159 lines (107 loc) · 7.13 KB

Agent Configuration for pyDeprecate

Important

For detailed coding standards, testing requirements, and contribution workflows, see the Contributing Guide. This file provides agent-specific behavioral instructions and quick reference only.

Overview

pyDeprecate is a lightweight Python library providing decorator-based deprecation for functions, methods, and classes with automatic call forwarding. Python 3.9+, zero runtime dependencies.

⚓ Before Any Work: Anchor with Repository Context

Important

Before starting any work, agents MUST anchor themselves with the repository context. Read these files in order:

Note

Anchor Links: GitHub generates anchors from section headers. Sections with emojis (e.g., ## 🚀 Quick Start) become #-quick-start (emoji → dash). Subsections without emojis (e.g., ### Test Organization) become #test-organization (no dash). All links follow this convention and are correct.

  1. Configuration files (source of truth):

    • pyproject.toml — project config, tool settings (ruff, mypy, pytest)
    • .pre-commit-config.yaml — pre-commit hooks configuration
    • setup.py — package metadata and dependencies
    • .github/workflows/*.yml — CI/CD pipeline configuration

  2. Documentation and guidelines:

    • CONTRIBUTING.md — contribution workflow, coding standards, testing requirements
    • README.md — project usage and API
    • src/deprecate/ — core library code to understand existing patterns

  3. Project structure: For codebase layout and file organization, explore the repository structure directly or see Test Organization for test file structure

Configuration Files Are Source of Truth

Warning

If documentation contradicts actual configuration, the configuration files have higher authority. When you detect a mismatch:

  1. Trust the config file (e.g., pyproject.toml, .pre-commit-config.yaml)
  2. Suggest updating the documentation to match reality
  3. Report the mismatch clearly to maintainers

When you find a mismatch:

Write a clear explanation linking to both sources, then let maintainers decide on the update action:

"I notice CONTRIBUTING.md:45 mentions using black for formatting, but pyproject.toml:23 actually configures ruff. The config file should be considered correct. Should the documentation be updated to reflect that ruff handles formatting?"

🧠 Agent Roles

Engineer

Scope: Core logic, CI/CD, and Python compatibility

Responsibilities:

  • Review PRs modifying src/ code
  • Validate deprecation warnings and function/class deprecations
  • Ensure Python patterns for backwards compatibility
  • Monitor CI/CD pipeline health

Guidelines:

Community-Scribe

Scope: Documentation and communication

Responsibilities:

  • Maintain README and documentation
  • Draft follow-ups after releases or PR merges
  • Help onboard new contributors
  • Ensure deprecation examples are documented

Guidelines:

Security-Watcher

Scope: Security monitoring and vulnerability assessment

Responsibilities:

  • Monitor dependencies for vulnerabilities
  • Review PRs for security issues
  • Follow Security Policy

🧭 Agent Behavioral Rules

Branch Management

Bug Fixes

  • Use Test-Driven Development (TDD): Write a failing test that reproduces the bug first, then implement the fix
  • See Fixing Bugs for complete workflow

New Features

Code Quality

  • Zero runtime dependencies — never add to install_requires
  • Type hints required — all function signatures must have type hints
  • No bare except: — always catch specific exceptions
  • Fast imports — no expensive module-level code
  • See Coding Standards for complete rules

Test Organization

  • Three-layer separation: targets in collection_targets.py, deprecated wrappers in collection_deprecate.py, test logic in test_*.py
  • Do not define targets or @deprecated wrappers directly in test files
  • See Test Organization for details

🚫 Critical Constraints

Never:

  • Add runtime dependencies
  • Commit sensitive information (.env, API keys)
  • Use bare except: clauses
  • Define deprecated wrappers inside test files
  • Skip test coverage for new features or bug fixes
  • Implement features without maintainer approval
  • Start work without first reading config files and guidelines

Always:

  • Anchor with repository context first — read config files (pyproject.toml, .pre-commit-config.yaml) and guidelines before any work
  • Trust config files over documentation — when mismatches occur, config files are the source of truth
  • Suggest documentation updates when you find mismatches between docs and actual configuration
  • Update docs immediately after any structural change — adding, moving, renaming, or deleting files/folders/modules must be followed by updating .github/CONTRIBUTING.md (project structure tree, Test Organisation table) and any other *.md that references affected paths or names. Do not wait to be asked.
  • Ensure pre-commit hooks are installed (they run automatically on commit)
  • Provide deprecated_in and remove_in versions
  • Include migration messages in deprecation warnings
  • Write tests first when fixing bugs (TDD)
  • Cover happy path, failure path, and edge cases in tests

🔗 Complete Guidelines

This file provides quick reference for agents. For complete, authoritative guidelines: