Opened 3 years ago

Last modified 13 months ago

#5309 enhancement new

Add @since markers to public APIs at release time, aided by a tool for identifying new public APIs

Reported by: exarkun Owned by:
Priority: normal Milestone: totally automated release infrastructure
Component: release management Keywords:
Cc: radix, thijs Branch:
Author: Launchpad Bug:

Description

Quite some time ago we started using @since in our epytext. This is a really nice feature to provide for end-users, so they can easily decide whether it's safe for them to use an API as they are learning about the API.

However, we don't apply this consistently, because everyone has to remember to do it to every public API each time they add a new public API. As a slightly smaller issue, all the old APIs are missing this information too.

Since this is a fairly automatic change, it's something of a waste of developer resources to require people to remember to do it anyway. Instead, some software should be involved.

It should be possible to take two versions of Twisted, discover all of the public APIs in each of them, and spit out a list of all of the APIs in one (the newer, hopefully) but not the other.

Programmatically rewriting the source code to include the @since marker is somewhat harder. Perhaps the first iteration of this would be a tool that just tells the release manager which APIs to add the marker to. A later tool might actually go all the way and automatically insert the markers.

Attachments (1)

public-interface.py (1.4 KB) - added by exarkun 3 years ago.
A crude approximation of the desired tool, not without shortcomings

Download all attachments as: .zip

Change History (8)

comment:1 Changed 3 years ago by DefaultCC Plugin

  • Cc radix added

comment:2 Changed 3 years ago by thijs

  • Cc thijs added

Changed 3 years ago by exarkun

A crude approximation of the desired tool, not without shortcomings

comment:3 Changed 3 years ago by exarkun

For the 12.0.0 release, after some post-processing, here's the output:

$ diff -U 0 11.1.0 12.0.0 | grep -Ev '^[@-]|(\+\+\+)'
+twisted.conch.checkers.spwd
+twisted.internet.abstract.AF_INET6
+twisted.internet.abstract.error
+twisted.internet.abstract.inet_pton
+twisted.internet.abstract.isIPv6Address
+twisted.internet.address.IPv6Address
+twisted.python.constants.NamedConstant
+twisted.python.constants.Names
+twisted.python.constants.ValueConstant
+twisted.python.constants.Values
+twisted.python.constants.count
+twisted.python.fakepwd.ShadowDatabase
+twisted.python.lockfile.platform
+twisted.web.template.CharRef

Clearly this has some false positives which need to be accounted for somehow.

comment:4 Changed 19 months ago by thijs

  • Keywords gsoc added

comment:5 Changed 17 months ago by exarkun

  • Keywords gsoc removed

What does this have to do with gsoc?

comment:6 Changed 13 months ago by therve

#4531 is likely to be a pre-requisite for this.

comment:7 Changed 13 months ago by exarkun

#4531 is likely to be a pre-requisite for this.

It's definitely related and an implementation using those APIs might have lower runtime costs. I doubt it's actually *required* though. A more naive implementation can just load all of the code (in two processes if it doesn't want to try to deal with the complexities of loading two versions of one Python package).

Note: See TracTickets for help on using tickets.