Repository navigation
Update policy and implementation for changelog entries #16569
Description
What is the problem this feature will solve?
This is jumping off of the discussion in #16562. The specific question there is whether the addition of type annotations should merit a changelog entry.
The current policy is basically that only user-facing changes should be highlighted with a changelog entry. That has been interpreted so that documentation updates or adding type annotations do not get changelogs. However, "user-facing" can reasonably be interpreted more liberally as changes that enhance the user or developer experience with astropy.
I would argue that #16562 is both a substantial amount of manual effort and substantially improves the user experience using the stats package. People reading the changelog should be made aware of this.
Being more self-serving, my own #16561 documentation update was at least 16 hours work and it would give me a good feeling to see that effort showing up in the changelog.
We are always trying to find ways to reward new contributors, but if they improve the documentation then that PR goes essentially unnoticed.
Describe the desired outcome
If a contributor wants a changelog entry associated with their PR, then it is allowed. For new-ish contributors, adding a changelog would be the default instead of opt-in.
Add a documentation changelog category to recognize this important category of contributions.
Additional context
No response
Activity
Cadair commentedon Jun 14, 2024
+1 to documentation changelog entries, we have them in sunpy land and I think they deserve being called out.
jeffjennings commentedon Jun 14, 2024
+1 from me too to everything proposed. The more easily people's contributions are recognized, the more I think they'll continue to contribute. And their effort deserves to be recognized in general. Thanks for opening the issue, Tom!
pllim commentedon Jun 14, 2024
v7.0.dev work is already well underway without this category. Adding it now would be unfair to the doc stuff already merged. Unless someone has time to dig those all up for v7.0, might be better to wait till we branch off v7.0.dev (i.e., after v7.0 release) to start.
That said, sometimes we also backport doc changes. Though big doc changes (e.g., dev doc overhaul and typing; does typing count as doc?) would not be backported anyway.
pllim commentedon Jun 14, 2024
Within reason? What if a new contributor comes and fix a minor typo but demands a change log? Where do we draw the line?
Also this sounds very subjective. How do you even automate the rules or ensure people implement this policy consistently?
mhvk commentedon Jun 15, 2024
I am 👎 on making changelog entries a form of credit, but 👍 on most of the actual suggestions to give more visibility.
For the reasoning: I feel strongly the logic for a changelog entry should remain that it is for the benefit of users/developers, not for assigning credit in any way, so am 👎 on adding entries that are not relevant for users, independent of who made the contribution. I do think giving credit is important, and that, e.g., as discussed in the coordination meeting, we should do more than adding a * for first-time contributors (maybe split those out to a separate subsection?). Furthermore, as also discussed in the coordination meeting, we could add a section of people who raised (first?) issues -- which is also a really relevant contribution -- and perhaps similarly a list reviewers (if easy to scrape). One might also think of adding number of PRs or loc changed, though to me that goes a bit too far, and can be looked up on github anyway.
I think a nice way to give credit to people who did more major pieces of work is to mention them in the what's new section. Indeed, for those pieces it may be particularly relevant to also credit reviewers; the best pieces merged often involved a lot of jointly figuring out how to do things. With what's new entries, that would be quite doable (i.e., not too much work). So, concretely I'd suggest adding something like "Contributed by XXX, {in collaboration with|reviewed by} YYY and ZZZ." to what's new entries (I think python does "contributed by" bits).
More directly on the changelog: I agree it is useful to both users and developers to be aware of bigger changes in documentation and typing, so I'm very much in favour of adding those (could be new related categories, i.e., entries of the form NNNN.typing.rst and NNNN.doc.rst, though using "other" may be fine since these are never going to be very common). Both PRs that triggered this issue are obvious candidates - to some users, it will be very relevant that
statsis completely typed (indeed, I think this warrants a what's new entry): people can try using it and report bugs, others may become aware astropy is adding typing and will start to help, etc,. etc. And it is similarly very relevant that the developer documentation has been revamped (also should have a what's new): people might think that perhaps this is something to check out to see if they can contribute; or they go see whether things can be done more simply than they thought.p.s. I don't think we've had any overhauls at the level of these two PRs, so am not too worried about missing changelog entries or what's new's for 7.0. At least, I think most other typing changes were not user-visible. Except perhaps that for cosmology? @nstarman, @eerovaher?
mhvk commentedon Jun 15, 2024
On the changelog entry type: I see that #16562 used
.feature.rst. I can see the logic for that, but I'd really rather not later have bugs in typing have.bugfix.rst- unless they are in an altogether separate typing category, i.e.,typing/NNNNN.bugfix.rst. But that breaks the bond with the relevant subpackage (also for docs). So, maybe stillNNNNN.other.rst?neutrinoceros commentedon Jun 15, 2024
I feel like moving the list of contributors from the bottom of a What's New page to the top would indeed make more sense than adding changelog entries to every doc change. How about we add an opt-out check-box for crediting PR authors in the markdown template ? By default, everyone authoring a change makes the list (unless they expressly request to be excluded), and we keep documenting only user-facing changes. We may need need infrastructure code to keep track of authors alongside changelog fragments, but this seems feasible and worth it to me.
+1 on this point
nstarman commentedon Jun 15, 2024
Cosmology has had some user-visible changes, but nothing on the level of stats. So probably not what's new worthy.
jeffjennings commentedon Jun 18, 2024
That makes sense,
otherseems best then.