Update wording of versionadded to neutral Added in [...] instead of New in [...].

[picnixz]

Resolves #11015.

@hugovk Do you think it is fine for Python docs?

@chrisjsewell Here I'm changing a localized string, hence possibly causing the same #11689. How should we deal with that? (we never fixed your issue by the way).

[hugovk]

Thanks for the ping, let me check with some others.

The wording of versionadded is currently "New in ...". However, the predicate "new" rots with time, and it is awkward to read "New in version 1.5" when this version was released 12 years ago.

I'm not sure about this, nothing is rotting, it was new back then.

I suggest to change the wording to the neutral "Added in ...".

Is "Added in" more neutral than "New in"? Does it need to be?

This also reflects better the intention that is embedded in the name of the pragma: versionadded.

Well this is true, but the distinction between "New in" and "Changed in" might be useful, compared with more similar "Added in" and "Changed in" being next to each othe.

Plus we have some things like:

New in version 3.2.

Changed in version 3.3: Added the optional func parameter.

Changed in version 3.8: Added the optional initial parameter.

https://docs.python.org/3/library/itertools.html#itertools.accumulate

Which would become:

Added in version 3.2.

Changed in version 3.3: Added the optional func parameter.

Changed in version 3.8: Added the optional initial parameter.

[hugovk]

I asked on the docs-community Discord, and the preference was for this change:

I would actually prefer "Added in ..." slightly. From an English point of view, they are similar.

I don't know how to describe it but its is "easier on the eyes" or something... I like it better

I agree as well. IMO, while I do understanding the rationale for "New" as it distinguishes them more visually, IMO "Added" is clearer as to the meaning, maps closer to the syntax and intended semantics, and sounds less like an advertisement.

No objections from me :)

---

Let's also ask a couple of theme maintainers, Furo's @pradyunsg and PyData Sphinx Theme's @trallard.

[trallard]

From a user experience POV I'd advocate for consistency for example we have Changed in so Added in aligns with the pattern of verb + version
While New in breaks this consistency.

Aside, I think both New in and Added in have similar if not equivalent meanings in the context of features and such.
Somehow the added feels more neutral indeed and taking into account the first point re consistency I'd advocate for Added in

[picnixz]

Thank you @hugovk !

So, we have an example where the community has a different feeling than a maintainer 😄

I said -1 because the chaining of "Added" felt weird to me but I actually misunderstood the fact that the "Added the ..." is explicitly written (I missed the Changed in). In addition, using version*added* for adding would be the best argument.

If people want a "new", maybe we could add a directive option for that / configuration value (and this could also help me in not breaking the translations, if any).

Anyway, I will wait a bit more for feedback (say, a week) but I think I'll follow the community on that one. By the way, were there common arguments against the change?

[hugovk]

By the way, were there common arguments against the change?

Nope, all were for the change!

[picnixz]

Do you want to have a look at it @chrisjsewell before I merge?

[chrisjsewell]

Do you want to have a look at it @chrisjsewell before I merge?

yeh all good thanks, and thanks for the feedback @hugovk / @trallard

interested in how we gather / record such feedback from the community, but that's for another time 😄

[chrisjsewell]

Here I'm changing a localized string, hence possibly causing the same #11689. How should we deal with that? (we never fixed your issue by the way).

and also for this, I think it would be get to have the translations in the next release; but I believe this is kind of a "back-and-forth" between transifex ,
i.e. the Added in version %s gets uploaded to transifex as part of the translation files, people (I don't know how they are 😅) then hopefully add the translations, then these get pushed back to sphinx (see #11626)

I definitely think this needs more explanation in the developer docs

@picnixz maybe for now open a separate issue, to remind us to check these translations before release

[trallard]

interested in how we gather / record such feedback from the community, but that's for another time 😄

I'd love to discuss/brainstorm this! It will be good to have better ways to capture and coordinate user feedback and user experience improvements.
We are running a documentation summit at PyCon so if you're there I'd love to catch up, otherwise I am sure we can find time/an opportunity to discuss online

[chrisjsewell]

We are running a documentation summit at PyCon

I'm guessing you mean python/docs-community#78; not in person (I'm residing in Munich these days), but would be interested to drop by online or something

[trallard]

Yes, that one! But happy to sync online.