core-workflow icon indicating copy to clipboard operation
core-workflow copied to clipboard

Add support for future-version workflows

Open jaraco opened this issue 3 years ago • 1 comments

In python/cpython#93965, I'm realizing that it would be nice when deprecating some functionality to simultaneously submit the changes to remove the deprecated behavior. That is, it would be nice to be able to author an issue and/or PR that targets Python N+.1 or N+.2 (where Python N is what's on main).

I think such a workflow could be readily achieved by:

  • Add tags for future versions (e.g. 3.13, 3.14) to Github.
  • Add a tag for deferred work (maybe call it "deferred").
  • Advise developers to close deferred items until they're valid.
  • When main is updated for a new version, re-open deferred tickets for the new version.

Other features could be added to streamline the process.

  • Automatically create new tags two versions into the future.
  • Disallow merging of "deferred" PRs.
  • Automatically close deferred items that aren't yet valid.
  • Automatically re-open deferred tickets when new branches are created (i.e. creation of 3.11 branch would re-open 3.12 deferred items).

This process would enable contributors to scope out a full lifecycle of a deprecation in a single bug with a couple of stacked PRs, one that is merged immediately and another that is deferred until the codebase is ready. This approach has the advantage of implementing the changes near to each other, avoiding loss of context in the interim, and offering a review of both changes together.

Except for initial setup, this process would require a tiny bit of extra work when cutting each new minor release.

jaraco avatar Jul 02 '22 21:07 jaraco

I think the approach can be simplified. We already have a DO-NOT-MERGE label that can be applied to PRs that should be used in the future, and we can just leave them open until it's time to merge them. To know when they can be merged, there a few different approaches:

  • use warnings._deprecated(name, "merge GH-12345 to fix this", remove=(3, N+1)) to warn once it's time to remove the function
  • add tests decorated with @skipIf(sys.version_info < (3, N+1), "merge GH-12345 to fix this") that activate once the release version is bumped;
  • enforce the use of the .. deprecated-removed: directive (see https://github.com/python/cpython/issues/92564) in order to track what and when is supposed to be removed;
  • manually go through the list of deprecated features in the whatsnew for each release (https://docs.python.org/3.12/whatsnew/3.12.html#deprecated)

In addition, we can use checklists in the issue to track all the relevant PRs (see this (unrelated) comment that contains an example of a checklist with issues/PRs/todos)

ezio-melotti avatar Jul 02 '22 22:07 ezio-melotti