"Date" of what's new is confusing

[methane]

BPO	29719
Nosy	@ned-deily, @methane, @csabella
PRs	bpo-29719: fix Date and Release field of whatsnew/3.6 #494 bpo-29719: Remove Date and Release field in whatsnew/3.6 #500 bpo-29719: Remove Date and Release field in whatsnew/3.7 and 8 #6093 bpo-29719: Remove Date and Release field in whatsnew/3.7 #6094

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2018-03-13.01:23:24.029>
created_at = <Date 2017-03-04.11:42:25.614>
labels = ['3.7', '3.8', 'docs']
title = '"Date" of what\'s new is confusing'
updated_at = <Date 2018-03-13.01:23:23.870>
user = 'https://github.com/methane'

bugs.python.org fields:

activity = <Date 2018-03-13.01:23:23.870>
actor = 'ned.deily'
assignee = 'docs@python'
closed = True
closed_date = <Date 2018-03-13.01:23:24.029>
closer = 'ned.deily'
components = ['Documentation']
creation = <Date 2017-03-04.11:42:25.614>
creator = 'methane'
dependencies = []
files = []
hgrepos = []
issue_num = 29719
keywords = ['patch']
message_count = 16.0
messages = ['288976', '288977', '288986', '289055', '289056', '289057', '289059', '289060', '289061', '290118', '290292', '290293', '313711', '313713', '313714', '313715']
nosy_count = 4.0
nosy_names = ['ned.deily', 'methane', 'docs@python', 'cheryl.sabella']
pr_nums = ['494', '500', '6093', '6094']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue29719'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8']

[methane]

See https://docs.python.org/3/whatsnew/3.6.html

At top:

:Release: |release|
:Date: |today|
:Editors: Elvis Pranskevichus <elvis@magic.io>, Yury Selivanov <yury@magic.io>

This |today| is replaced with day when HTML is build (like "Last updated:" in footer). This is near to the date this page is modified last on docs.python.org, until clean rebuild happens.
But other cases, this shows only when this HTML is built. It's confusing.

How about replacing |today| to Python 3.6.0 release date, or removing the ":Date: |today|" line?

[ned-deily]

It's a bit confusing but:

1. https://docs.python.org/3/whatsnew/3.6.html

is the URL for the current 3.6 branch, in other words, what will be in the next 3.6 release. These are rebuilt as changes are checked in.

2. https://docs.python.org/release/3.6.0/whatsnew/3.6.html

(which is linked from https://www.python.org/doc/versions/) is the URL for the docs corresponding to the 3.6.0 release. These are built at release time and then never change.

Does that help?

[methane]

is the URL for the current 3.6 branch, in other words, what will be in the next 3.6 release.

"next 3.6 release" means 3.6.1?

These are rebuilt as changes are checked in.

There are some commit for fixing something after 3.6.0 released.
But I think rebuild can be happen without changing the page. For example, major sphinx version up, fixing template, update version of imported js libraries.
And as I said, the document may be built on other machine. In this case, this |today| is not related to last commit date of this page. It seems unmeaningful.

So I still this ":Date:" should be release date, or removed.

[ned-deily]

Sorry, I disagree. I think the point of adding these directives is that shows for what release of 3.6.x they apply. It is expected that the What's New documents may be updated during the lifecycle of a major release and having the release and date there lets the reader know that they are update. For example, at the moment https://docs.python.org/3.6/whatsnew/3.6.html shows:

What’s New In Python 3.6
Release: 3.6.1rc1
Date: March 05, 2017

which is correct.

[methane]

https://docs.python.org/3.7/whatsnew/3.6.html shows:
Release: 3.7.0a0
Date: February 15, 2017

Is it make sense for you?

[methane]

Additonally, unlike "changelog", "What's New" only shows difference between 3.5 and 3.6. It won't be updated to describe changes between 3.6.0 and 3.6.1.

[ned-deily]

Additonally, unlike "changelog", "What's New" only shows difference between 3.5 and 3.6. It won't be updated to describe changes between 3.6.0 and 3.6.1.

That's not always true. There are occasionally changes made in the What's New document for maintenance releases. See, for example, https://docs.python.org/3.5/whatsnew/3.5.html. You'll find references to 3.5.1 and 3.5.2 there.

If it's truly bothering people, a better solution is to just remove the release and date directives. They aren't there for earlier releases. We can live without them.

[methane]

I'm sorry, I was wrong.

https://docs.python.org/3.5/whatsnew/3.5.html

asyncio has "Updates in 3.5.1:" section.
provisional package will introduce updates in what's new in bugfix release.

So is it OK to just removing Date and Release field?
"Date (when this HTML is built)" and "Release (of branch this page is built)" are not good for "What's New In 3.6" page.

[ned-deily]

Heh, it looks like we agree!

[ned-deily]

New changeset 0acdea7 by Ned Deily (INADA Naoki) in branch '3.6':
bpo-29719: Remove Date and Release field in whatsnew/3.6 (GH-500)
0acdea7

[methane]

New changeset 4e1a065 by INADA Naoki in branch '3.6':
bpo-29719: Remove Date and Release field in whatsnew/3.6 (GH-500)
4e1a065

[methane]

New changeset 2225dda by INADA Naoki in branch 'master':
bpo-29719: Remove Date and Release field in whatsnew/3.6 (GH-494)
2225dda

[csabella]

I believe this can be closed as 'fixed'?

[ned-deily]

New changeset a34510a by Ned Deily in branch 'master':
bpo-29719: Remove Date and Release field in whatsnew/3.7 and 8 (GH-6093)
a34510a

[ned-deily]

New changeset d461ed8 by Ned Deily in branch '3.7':
bpo-29719: Remove Date and Release field in whatsnew/3.7 (GH-6094)
d461ed8