Compatibility Notes — Documenting Platform and Dependency Support

In this tutorial, you will learn about Compatibility Notes. We cover key concepts, practical examples, and best practices to help you master this topic.

Compatibility notes document which platforms, dependencies, and environments your software supports. Developers check compatibility before adopting a library or tool. Clear compatibility documentation prevents integration surprises.

In this lesson, you will learn how to write compatibility notes that help developers make informed decisions.

What You'll Learn

You will document platform support, dependency requirements, compatibility tables, and deprecation timelines.

Why It Matters

Developers cannot use your software if it does not run in their environment. Compatibility documentation is the first thing developers check.

Real-World Use

DodaTech maintains a compatibility matrix for DodaZIP showing supported Python versions, operating systems, and hardware architectures. The matrix is updated with every release.

flowchart LR
  A[Compatibility] --> B[Platform Support]
  A --> C[Dependency Versions]
  A --> D[Hardware Requirements]
  A --> E[Deprecation Timeline]
  B --> F[OS and Architecture]
  C --> G[Minimum and Tested]
  D --> H[RAM, Disk, CPU]
  E --> I[Removal Schedule]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Platform Support

Document which operating systems, architectures, and environments are supported. Use a table for quick reference.

Specify the level of support for each platform: fully supported, partially supported with limitations, or deprecated.

Update the compatibility matrix with every release. Remove unsupported platforms from the documentation.

# DodaZIP Platform Support Matrix

| Platform     | Support Level | Notes                                    |
|-------------|---------------|------------------------------------------|
| Linux x86_64 | Full          | Primary development platform             |
| Linux ARM64  | Full          | Supported since v2.0                     |
| macOS x86_64 | Full          | Tested on macOS 13+                      |
| macOS ARM64  | Full          | Native Apple Silicon support             |
| Windows x86_64 | Full        | Windows 10 and 11                        |
| Windows ARM64 | Partial      | No native ARM build yet                  |

Dependency Versions

Document minimum, maximum, and tested versions of all dependencies. Use tilde or caret ranges to communicate what is supported.

When a dependency reaches end of life, announce the removal timeline. Give developers time to upgrade their environments.

Include Python or language version requirements. Specify the minimum version and the versions tested in CI.

# Compatibility configuration for DodaZIP

# Python version support
# Minimum: 3.9
# Tested: 3.9, 3.10, 3.11, 3.12, 3.13
# Dropping 3.8 in v3.0 (planned 2027 Q1)

REQUIRED_PYTHON = (3, 9)

# Dependency version ranges
DEPENDENCIES = {
    "click": ">=8.0,<9.0",
    "rich": ">=12.0,<14.0",
    "pyyaml": ">=6.0,<7.0",
}

def check_compatibility(python_version: tuple) -> bool:
    """Check if the current Python version is supported."""
    if python_version < REQUIRED_PYTHON:
        raise RuntimeError(
            f"Python {REQUIRED_PYTHON[0]}.{REQUIRED_PYTHON[1]}+ required. "
            f"Current: {python_version[0]}.{python_version[1]}"
        )
    return True

Common Mistakes

1. No Compatibility Documentation

Not documenting which platforms or versions are supported. Developers must guess or test empirically.

2. Overly Broad Claims

Supporting all platforms in documentation but not testing them. Developers encounter issues on untested platforms.

3. No Deprecation Timeline

Removing support without prior notice. Give developers at least one version cycle to migrate.

4. Conflicting Information

Different pages showing different supported versions. Keep compatibility information centralized.

5. No Minimum Version

Documenting tested versions but not minimum versions. Developers do not know the floor.

6. Ignoring End-of-Life Dependencies

Supporting dependencies that have reached end of life. Update or announce removal.

7. Hardware Requirements Missing

Not documenting RAM, disk space, or CPU requirements. Developers cannot plan their infrastructure.

Practice Questions

1. What should a compatibility matrix include?

Platforms, architectures, support levels, and notes about limitations.

2. Why document dependency version ranges?

Developers need to know what versions work together. Range notation communicates compatibility clearly.

3. What is a deprecation timeline?

A schedule for removing support for a platform or dependency. It gives developers time to migrate.

4. Why is it important to document minimum but not maximum versions?

Minimum tells developers what they need to have. Maximum tells developers what they cannot exceed.

5. Challenge: Create a compatibility matrix for a project you use or know. Include OS support, dependency versions, hardware requirements, and a deprecation timeline.

FAQ

Mini Project

Create a compatibility documentation page for a project you use. Include a platform support matrix, dependency version table, hardware requirements, and a deprecation timeline for any features or platforms slated for removal.

What's Next

Next: Code Snippets Do's and Don'ts