Skip to content

Write the versioning policy into AGENTS.md #323

Closed

Description

@lesnik512

Two minors shipped breaking changes: 1.11.0 dropped Python 3.10 (chore!, #270), and 1.12.0 moved Litestar tracing to Litestar's OpenTelemetryPlugin (feat!, #279), with a "Breaking changes" section in its release notes. Nothing in the repo says when a change needs a major. AGENTS.md's alias rule (AGENTS.md:51-53) makes every rename a silent alias and gives no path for removing one.

Work

  • Add a short versioning section to AGENTS.md:
    • what counts as breaking, for example: a user's working code or deployed behaviour changes without them editing anything. That covers new defaults, removed names, raised floors and a changed HTTP surface;
    • breaking means a major release;
    • whether dropping an end-of-life interpreter is an exception. 1.11.0 treated it as one, and modern-python/lite-bootstrap#272 plans the same for 3.11. Write down whichever is decided;
    • how a rename retires: the alias warns with DeprecationWarning for at least one minor and is deleted in the next major (this replaces the "silent alias" wording; see Remove deprecated aliases, after a 1.x release that warns about them #314);
    • breaking changes get a "Breaking changes" section in the release notes, as 1.12.0 has.
  • Keep it to rules an agent cannot infer from the code, per the existing "Code style" framing.

Verify: just adr-check and the links job pass, and every line of the new section states a rule.

Activity

  1. added this to the 2.0.0 milestone on Oct 24, 2026
  2. added
    documentationImprovements or additions to documentation
    needs-triageMaintainer needs to evaluate this issue
    on Oct 24, 2026
  3. removed this from the 2.0.0 milestone on Oct 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationneeds-triageMaintainer needs to evaluate this issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions