feature: suppression configruation for intentional changes/breakages between versions

[RonnyPfannschmidt]

this is a first draft idea for configuring suppressions of warnings/errors per versions
i let a sonnet model generate the bulk of the suggestion here
its by no means complete or well rounded but i think its a nice starting point for thinking - it clearly needs refinement before it can be pushed further

Feature Request: Version-Based TOML Suppression Files for Expected API Changes

Problem

Griffe reports all API changes as warnings, including intentional changes between releases. This creates noise in CI/CD and makes it hard to distinguish unintended breaking changes from deliberate API evolution.

Solution: Version-Based TOML Configuration

Use TOML files organized by version in a .griffe/suppressions/ directory.

Directory Structure

project-root/
├── pyproject.toml
└── .griffe/
    ├── suppressions/
    │   ├── v2.0.0.toml
    │   ├── v1.5.0.toml
    │   └── v1.4.0.toml
    └── config.toml

Suppression File Format

.griffe/suppressions/v2.0.0.toml

[metadata]
version = "2.0.0"
description = "Major version with planned API restructuring"
created = "2024-01-15T10:30:00Z"
author = "team@example.com"

[[suppressions]]
type = "object_removed"
object = "Configuration.git_describe_command"
reason = "Moved to scm.git.describe_command as part of configuration restructure"
issue = "https://github.com/project/issues/123"
deprecated_since = "1.8.0"

[[suppressions]]
type = "parameter_removed"
object = "Configuration.from_file"
parameter = "_require_section"
reason = "Deprecated parameter removed in v2.0 as planned"
deprecated_since = "1.9.0"

[[suppressions]]
type = "parameter_default_changed"
object = "Configuration.__init__"
parameter = "git_describe_command"
old_value = "None"
new_value = "_GitDescribeCommandDescriptor()"
reason = "Implementing deprecation descriptor pattern"

# Pattern-based suppressions
[[suppressions]]
type = "attribute_value_changed"
pattern = "*.DEFAULT_*"
reason = "Updated default values for improved behavior"

Command-Line Usage

# Use suppressions automatically
griffe check mypackage --use-suppressions

# Specify version explicitly
griffe check mypackage --suppressions-version v2.0.0

# Generate suppression template
griffe check mypackage --generate-suppressions v2.0.0

# Validate suppression files
griffe validate-suppressions

# List suppressed changes
griffe list-suppressions --version v2.0.0

pyproject.toml Integration

[tool.griffe]
suppressions_enabled = true
suppressions_dir = ".griffe/suppressions"
require_documentation = true
strict_mode = false

Version Detection

Automatic detection via:

1. --suppressions-version flag
2. Git tags
3. pyproject.toml version
4. Environment variable GRIFFE_VERSION
5. Latest file in suppressions directory

Example Workflow

1. Make API changes
2. Run griffe check --generate-suppressions v2.0.0
3. Fill in generated template with reasons and metadata
4. Run griffe validate-suppressions
5. CI/CD passes with griffe check --use-suppressions

Benefits

• Version Organization: Clear separation by release
• TOML Format: Familiar to Python developers
• Rich Metadata: Track reasons, issues, deprecation timeline
• Template Generation: Auto-generate from detected changes
• CI/CD Friendly: Version controlled, reviewable
• Documentation: Files serve as API evolution history