diff --git a/pep-0512.txt b/pep-0512.txt index 6d16ec209..b648b6433 100644 --- a/pep-0512.txt +++ b/pep-0512.txt @@ -654,6 +654,8 @@ Required: - `Deprecate sys._mercurial`_ (http://bugs.python.org/issue27593) - `Update PEP 101`_ + - Email python-checkins for each commit + - Message #python-dev for each commit * In progress @@ -735,7 +737,7 @@ keep/add attribution. How to handle the Misc/NEWS file -------------------------------- -There are three competing approaches to handling +There are three competing approaches to handling files like ``Misc/NEWS`` [#news-file]_. One is to add a news entry for issues on bugs.python.org [#b.p.o]_. This would mean an issue that is marked as "resolved" could not be closed until a news entry is added in the @@ -747,7 +749,12 @@ Versions field of the issue also ties the news entry to which Python releases were affected. A script would be written to query bugs.python.org for relevant new entries for a release and to produce the output needed to be checked into the code repository. This -approach is agnostic to whether a commit was done by CLI or bot. +approach is agnostic to whether a commit was done by CLI or bot. A +drawback is that there's a disconnect between the actual commit that +made the change and the news entry by having them live in separate +places (in this case, GitHub and bugs.python.org). This would mean +making a commit would then require remembering to go back to +bugs.python.org to add the news entry. A competing approach is to use an individual file per news entry, containing the text for the entry. In this scenario each feature @@ -768,14 +775,17 @@ information is captured by the "What's New" documents which are organized). The benefit of this approach is that it keeps the changes with the code that was actually changed. It also ties the message to being part of the commit which introduced the change. For a commit -made through the CLI, a script will be provided to help generate the -file. In a bot-driven scenario, the merge bot will have a way to +made through the CLI, a script could be provided to help generate the +file. In a bot-driven scenario, the merge bot could have a way to specify a specific news entry and create the file as part of its flattened commit (while most likely also supporting using the first line of the commit message if no specific news entry was specified). -Code for this approach has been written previously for the Mercurial -workflow at http://bugs.python.org/issue18967. There is also tools -from the community like https://pypi.python.org/pypi/towncrier, +If a web-based workflow is used then a status check could be used to +verify that a new entry file is in the pull request to act as a +reminder that the file is missing. Code for this approach has been +written previously for the Mercurial workflow at +http://bugs.python.org/issue18967. There is also tools from the +community like https://pypi.python.org/pypi/towncrier, https://github.com/twisted/newsbuilder, and http://docs.openstack.org/developer/reno/. @@ -784,6 +794,11 @@ approach allows for keeping the NEWS file as a single file. It does run the risk, though, of failure and thus blocking a commit until it can be manually resolved. +Discussions at the Sep 2016 Python core-dev sprints has led to the +decision that the separate files approach will be used. It seems to +have the right balance of flexibility and potential tooling out of the +three options while solving the motivating problem. + Naming the bots ---------------