Repository: sphinx-doc/sphinx

Issue:
Change wording of `versionadded` to "Added in..."
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 suggest to change the wording to the neutral "Added in ...". 

This also reflects better the intention that is embedded in the name of the pragma: `versionadded`.


Discussion:
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.

picnixz: Taking your opinion into account, I think we should not change the wording then, especially when you do not specify anything except the version number.

Well, the PR was easy so it was not much work on my side. However, I am convinced that

>   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.

is worse than what you currently have (it feels weird to be actually). As such, I will vote for a -1 (also it solves the issue with translations if we don't change it).

Well, the PR was easy so it wasn't much work on my side. 

> Thanks for the ping, let me check with some others.

I'll wait for the feedback of others. But just with your example, I think I won't go for the change (and close the related issue).

hugovk: I asked on the [docs-community Discord](https://docs-community.readthedocs.io/en/latest/community/contributing.html), 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 :smile: 

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 https://github.com/sphinx-doc/sphinx/issues/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 (see https://github.com/sphinx-doc/sphinx/pull/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

Patch:
diff --git a/CHANGES.rst b/CHANGES.rst
index 3becdc1db..a02119c1e 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -57,6 +57,11 @@ Features added
   .. _OSC 8: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
   .. _groff: https://lists.gnu.org/archive/html/groff/2021-10/msg00000.html
 
+* #11015: :rst:dir:`versionadded` wording changes from ``New in [...]``
+  to ``Added in [...]``.
+  Patch by Bénédikt Tran.
+
+
 Bugs fixed
 ----------
 
diff --git a/sphinx/domains/changeset.py b/sphinx/domains/changeset.py
index c0550f5b4..5ffabcf50 100644
--- a/sphinx/domains/changeset.py
+++ b/sphinx/domains/changeset.py
@@ -20,7 +20,7 @@
 
 
 versionlabels = {
-    'versionadded':   _('New in version %s'),
+    'versionadded':   _('Added in version %s'),
     'versionchanged': _('Changed in version %s'),
     'deprecated':     _('Deprecated since version %s'),
     'versionremoved': _('Removed in version %s'),
diff --git a/sphinx/util/nodes.py b/sphinx/util/nodes.py
index 3cf199a8f..bbc1f64e4 100644
--- a/sphinx/util/nodes.py
+++ b/sphinx/util/nodes.py
@@ -110,7 +110,7 @@ def get_full_module_name(node: Node) -> str:
 def repr_domxml(node: Node, length: int = 80) -> str:
     """
     return DOM XML representation of the specified node like:
-    '<paragraph translatable="False"><inline classes="versionmodified">New in version...'
+    '<paragraph translatable="False"><inline classes="versionadded">Added in version...'
 
     :param nodes.Node node: target node
     :param int length:


Test patch:
diff --git a/tests/test_builders/test_build_changes.py b/tests/test_builders/test_build_changes.py
index b340c8d54..b537b8751 100644
--- a/tests/test_builders/test_build_changes.py
+++ b/tests/test_builders/test_build_changes.py
@@ -9,7 +9,7 @@ def test_build(app):
 
     # TODO: Use better checking of html content
     htmltext = (app.outdir / 'changes.html').read_text(encoding='utf8')
-    assert 'New in version 0.6: Some funny stuff.' in htmltext
+    assert 'Added in version 0.6: Some funny stuff.' in htmltext
     assert 'Changed in version 0.6: Even more funny stuff.' in htmltext
     assert 'Deprecated since version 0.6: Boring stuff.' in htmltext
 
diff --git a/tests/test_builders/test_build_html_5_output.py b/tests/test_builders/test_build_html_5_output.py
index 0350efd67..ece6f495a 100644
--- a/tests/test_builders/test_build_html_5_output.py
+++ b/tests/test_builders/test_build_html_5_output.py
@@ -113,7 +113,7 @@ def checker(nodes):
     # abbreviations
     ('markup.html', ".//abbr[@title='abbreviation']", '^abbr$'),
     # version stuff
-    ('markup.html', ".//div[@class='versionadded']/p/span", 'New in version 0.6: '),
+    ('markup.html', ".//div[@class='versionadded']/p/span", 'Added in version 0.6: '),
     ('markup.html', ".//div[@class='versionadded']/p/span",
      tail_check('First paragraph of versionadded')),
     ('markup.html', ".//div[@class='versionchanged']/p/span",
diff --git a/tests/test_intl/test_intl.py b/tests/test_intl/test_intl.py
index e54339c12..6b1e9bae0 100644
--- a/tests/test_intl/test_intl.py
+++ b/tests/test_intl/test_intl.py
@@ -967,7 +967,7 @@ def get_content(result, name):
     assert expect1 == matched_content
 
     expect2 = (
-        """<p><span class="versionmodified added">New in version 1.0: </span>"""
+        """<p><span class="versionmodified added">Added in version 1.0: </span>"""
         """THIS IS THE <em>FIRST</em> PARAGRAPH OF VERSIONADDED.</p>\n""")
     matched_content = get_content(result, "versionadded")
     assert expect2 == matched_content