Ticket #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|
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.