Before we start adding the directive to any docstrings, we should document a policy on it and get that merged.

Policy proposal:

.. versionadded:: should be added to the docstring for new classes, functions, methods and parameters. The entry should be placed at the end of the description block and before the Parameters section. For parameters, it should be placed at the end of the description. For minor releases 3.x.0 the bugfix-version should be left out i.e. .. versionadded:: 3.x.

class Foo:
    """
    This is the summary.

    Followed by a longer description block. Consisting of multiple lines
    and paragraphs.

    .. versionadded:: 3.5

    Parameters
    ----------
    a : int
        The first parameter.
    b: bool, default: False
        This was added later.

        .. versionadded:: 3.6
    """

    def set_b(b):
        """
        Set b.

        .. versionadded:: 3.6

        Parameters
        ----------
        b: bool

Notes

• The motivation to place the tag "at the end" is that this info will be needed only in some situations and is less prominent there compared to placing it at the top.
• While supported I would not add versionadded to whole modules. Instead, let's simply tag all contained elements. That's more discoverable.

This would be a very welcome addition for downstream libraries.

For documentation of specific parameters, the admonition produced by versionadded directive takes up a lot of vertical space, so I wonder whether just having "Put "Added in version x" in the description is a preferable policy.

@melissawm had the (great) suggestion that this should be addressed as two concurrent PRs - one with the policy and one with some sample output. Doing so would allow for easier policy tweaking on the basis of output while still keeping them independent.

@timhoffm my thinking was:

• if it gets a what's new, it gets a version added
• if it gets an API change, it gets a versionchanged

mostly because that seemed consistent with current policy and very easy to document. I don't think your comment contradicts and is more guidance on placement, but I'm not sure.

For documentation of specific parameters, the admonition produced by versionadded directive takes up a lot of vertical space, so I wonder whether just having "Put "Added in version x" in the description is a preferable policy.

I belive there is value in having this styled differently from plain text. We can tune the spacing using CSS:

e.g. adding

dl.field-list .versionadded p {
    margin-top: 0.1em;
    margin-bottom: 0.1em;
}

dl.field-list .versionadded {
    margin-top: 0.3em;
}

quickly tested on pandas results in

instead of

@story645 @melissawm I don't follow why it's important to keep two independent PRs. Policy and some first samples must be developed together and match. I would have no issue doing this simultaneously within one PR.

Cause Tom said in this thread that policy should be merged first but the discussion on the call was about creating some samples first.

My memory of the call was that the next action was a PR adding the policy (basically what @timhoffm wrote out in #23506 (comment)) as a starting place for the discussion, but I see the notes do not agree with my memory so I apologize for not making sure everyone was on the same page before we moved on.

I agree with Tim that doing the policy and a few examples (plus it seems some styling work) in the same PR makes good sense.

The notes are idiosyncratic 😉. If anything in them is meant to be a formal roadmap forward for a subject, we should probably stop and write it out carefully.

But I don't think this particular issue is particularly contentious that we can't be flexible on how to proceed. In particular my understanding is that we wanted a policy before we expect everyone to add these going forward, but I don't think that precluded a few examples as well.

I have a concern that "some" is worse than "none" and that this may be a case were (at least going forward), we need to boil the ocean.

have a concern that "some" is worse than "none"

Which is one of the reasons Melissa suggested the split PRs & I think it's a good idea. Then the policy can go in and we can build up the examples (for example 1 PR per major doc version). It also lets us split up the work more easily.

I thought the plan was to just do this going forward. If we have to go back and do every method we will never do this.

I thought the plan was to just do this going forward. If we have to go back and do every method we will never do this.

Yeah, my rough proposal is target 3.7 for the policy, maybe 3.6 if all the 3.6 features can get marked up quickly enough. Then over time maybe the previous releases get marked up, which is mostly tedious but not difficult if we can agree on a straightforward enough policy.

There's work to do to make sure all the 3.7 PRs get labeled and there's a question about going back (possibly a sprint task?) but I think this is done enough to close this issue.