Repository navigation
Use a YAML file as the basis for the change log #10334
Description
Description
The repo at https://github.com/taldcroft/astropy-changelog shows a proof of concept for changing the basis of the astropy changelog from the CHANGES.rst file to a new CHANGES.yml file. Please see the README there for details. The driver for this and initial discussions were captured in an astropy-dev email thread in Oct 2016 (subject "Proposal for a new changelog system").
This was discussed in more detail at the 2019 coordination meeting in Socorro, with the agreement at the time that @bsipocz and @Cadair would develop a different system that uses information embedded in the PR description and/or GitHub metadata. While arguably a better solution, 6 months have passed with no progress, and in fact the details of the better solution were not captured in any written form. @bsipocz has stated in private conversation that she does not have time to spend on this given many other higher priorities and is OK with the YAML solution.
I propose moving forward on the YAML solution unless @Cadair can commit to developing the better solution in the next few months. All details of the YAML solution and how it gets implemented (both code and process) are certainly open for discussion here.
The problems in the current CHANGES.rst implementation are real and persist. I personally had to rebase at least 5 times due to a changelog conflict in the last few weeks (including once literally ten minutes after the last rebase), and now I see the 5-day old #10296 is already blocked from merge because of a changelog conflict. I also made a mistake in the placement of a change entry.
Activity
mhvk commentedon May 9, 2020
👍 to solving this before the next release, and also 👍 for using the
yamlfile by default.That said, I still have some preference to avoid a roll-our-own approach, and think it might be better to just copy what numpy does (though they limit it to "what's new" like items, relying on the bug label to collect those from PRs directly, but there is nothing intrinsic that prevents using it generally); see https://github.com/numpy/numpy/blob/master/doc/release/upcoming_changes/README.rst, item 5 in the numpy developer instructions and their pyproject.toml for setup.
That said, IIRC, your "homebrew" approach was not exactly super-complicated, i.e., I should not overly worry about maintainability.
pllim commentedon May 9, 2020
Would you be willing to implement this at a small scale as a proof of concept? It is hard for me to see how this really works without a practical example. We need to support at least these scenarios:
Note that, sometimes manual backport is necessary.
mhvk commentedon May 9, 2020
@pllim - was this directed at me? @taldcroft has a POC on his branch already.
pllim commentedon May 9, 2020
taldcroft commentedon May 10, 2020
@pllim - the proof of concept (POC) https://github.com/taldcroft/astropy-changelog has the real existing astropy changelog represented as YAML. I'm not sure if that is what you are looking for.
taldcroft commentedon May 10, 2020
Agreed on trying to avoid inventing something new.
About using towncrier ala numpy and sunpy, the biggest obstacle I see is the lack of subpackage. This is a key level of granularity that is really a requirement for astropy IMO. So what would it take to have
<PR>.<subpackage>.<entry_type>.rst? From what I can see in the rather terse towncrier documentation, this is not supported.Smaller niggles:
mhvk commentedon May 10, 2020
Ah, good point about the subpackages. I think that can be solved somewhat by entering fragments as something like
coordinates-12345.bugfix.rst- this will order them correctly (but not give a link to github).Anyway, since I don't think I'll be the one doing this, and do think your scheme is sensible, I'm quite happy to just go with that.
pllim commentedon May 11, 2020
tl;dr -- Are we going to backport this new format to all the old releases or only for going forward?
Okay, so I guess it's everything then?
pllim commentedon May 11, 2020
As far as I can find on the POC repo, the workflow for maintainer is still undetermined, as well as the cadence of YAML to RST generation.
taldcroft commentedon May 11, 2020
Indeed these are the key unresolved issues.
taldcroft commentedon May 11, 2020
I thought some more and looked a little at towncrier. I think adding support for subsections might not be too difficult (famous last words). See : twisted/towncrier#230.
26 remaining items
taldcroft commentedon Jan 9, 2021
I am not worried about git, but rather command line
lsor navigating to that directory in GitHub.One hacky solution is to make subdirs representing the last 2 digits of the PR number, so e.g. 10334 would become 34/10334. It's not great, but this is easily predictable by humans and will effectively reduce the average number of files in a single directory by a factor of 100.
bsipocz commentedon Jan 12, 2021
I can't help feeling that this is converging to the combination of the worst from both approaches. I fail to see having the many files in subdirs will be much easier to irregular contributors than the current changelog, while adding the YAML structure would also add complexity (a reminder that the yaml format caused issues e.g. at the sunpy paper, most contributors had issues of submitting a properly formatted one, even though there was a template).
And it certainly won't be convenient for looking for a summary of recent changes either, basically checking things on github is out of the question one can only do the command line.
taldcroft commentedon Jan 12, 2021
What about going back to the single file model, with a utility script in the astropy git repo (but not in the package) that people can run. This would do a few things:
saimn commentedon Jan 12, 2021
In other related news, it seems towncrier now have an active maintainer and will have a new release hopefully soon...
embray commentedon Jan 16, 2021
I should clarify, I did not suggest breaking the existing changelog into a million tiny files; that would be pointless. Just that it should be possible to concatenate multiple YAML files together automatically to build the full changelog database, which would enable keeping entries for new PRs in single files if desired. If they ever build up to a large number an occasional maintenance task can be to cat them all into the "main" file and delete them, but it doesn't have to be done every time either.
I also agree that a utility script for listing / filtering recent changes would be extremely useful regardless. It would be useful with or without allowing multiple files.
embray commentedon Jan 18, 2021
In any case, just a few weeks back on the project I'm already tired of dealing with minor changelog formatting issues every time one of my PRs lags. I'll work on integrating Tom's solution into a PR and hopefully we can leave the bikeshedding for when problems with it actually occur.
bsipocz commentedon Jan 19, 2021
I yet to see how to avoid tiring the people with the proper yaml formatting, as well as update all the scripts and bots to deal with the new format, while maintaining the readability of browsing the changelog in master in a humanly readable format. The yaml approach, as Simon mentioned above, still has the issue of updating the "formatting issues" when there is a milestone update on an outdated PR, etc. (or I'm not sure what other changelog formatting issues you are referring to).
taldcroft commentedon Jan 21, 2021
@bsipocz - about updating all the scripts and bots, do you have an initial list of impacts? I expect that the code in those scripts will become simpler / more sane since they just need to read a nicely structured (machine-readable) data file instead of scraping a human-readable document.
As I mentioned, there is not a requirement that contributors generate the YAML by hand if you allow for a helper script in the source repo that does the job. So unless you reject that idea outright I don't see a reason to keep going with the "tiring people" with YAML objection. As a reminder such a script can also solve the "thousands of files" problem and the merge conflicts problem by putting all the YAML entries into a single file and placing it randomly. Yes, it's a new process for contributors, but arguably easier if there is a simple script that just asks questions and makes sure the answers are sensible.
I agree that not having convenient access to the formatted version of the changelog in master is a real issue. Could we have a GitHub action that generates the latest CHANGES.rst and commits to master when a PR gets merged to master? Seems possible and maybe not that hard from what I know. @pllim?
pllim commentedon Jan 21, 2021
Theoretically, yes. Whether the default token access is enough or not, I am not sure. If someone opens a PR to implement this new workflow, I can try to build that on top of the PR and see.
bsipocz commentedon Jan 21, 2021
Ok, I give up. I don't see how a custom helper script will help casual contributors who find editing a text file cumbersome. After all there is a script to figure out the number for the next pr, yet it's always being complained about as an issue.
I neither see how it will help with milestone changes that I presume caused the annoyance @embray referred to.
And parsing it with a new action is yet as another tiny piece of infrastructure while otherwise the home grown infrastructure is already attacked all the time that it should be cut back more.
So yes, the random order in yaml might help with conflicts (of it's random, but as humans are involved I would not be surprised to see edits mostly to the beginning or end of it causing more conflicts than we currently have), it's the same or only workaround for the rest of the things the changlog currently does.
saimn commentedon Jan 21, 2021
One thing that is not clear to me with the YAML solution is the workflow with respect to milestones and backports. Having to put the milestone in the YAML file is annoying because it means that you have to wait for a maintainer to set the milestone, which often changes following discussions in a PR. So people will need to edit the YAML. And if the PR is to be backported, should PR authors specify multiple milestones ?
And then when backporting PRs, it happens that a PR cannot be backported, or that another PR is backported though it was not planned initially, so again the milestone needs to be updated (on the release branch ? then the YAML file will need to be merged back to master).
All of this is not a problem with towncrier since the changelog fragment does not need the milestone.
taldcroft commentedon Jan 22, 2021
@saimn - All of your comments are fair enough, but I would say that the YAML solution represents an improvement over the current process, which is the goal.
Right now the contributor is implicitly matching the milestone by virtue of placement of the change text in CHANGES.rst (i.e. which section it goes in). As a reviewer I find this to be a pain because in order to check the changelog entry I need to typically open the file and scroll around to see that it is in the correct section. In the YAML version it is entirely obvious. All of the problems you mention are also problems of the current process, and made worse. E.g. if the milestone changes, right now the PR author has to move the text. In the YAML version the PR author just edits
4.2.1=>4.3.0. So to my mind that represents a small improvement.The idea is for the YAML to explicitly specify all versions to which the PR will be backported. This puts the burden on the maintainer (at the time of approving) to ensure this is correct. In the circumstance that the maintainer made a mistake and the backport cannot be completed then the release manager would indeed make a commit to master to fix the target releases for the PR. This seems simpler to me than the current process where the release manager needs to actually move the changelog entry to a new section in CHANGES.rst (for a failed backport).
To be clear, if towncrier is going to be supported (and hopefully by more than just one person), and somebody can show that it can fully support generating the current astropy CHANGES.rst, and work through the process changes, then I'm OK with that.
I'm just not happy with the status quo, "do nothing" solution.
Onel comment on YAML vs towncrier. There is a philosophy difference in the approach. In YAML, the
changes.ymlfile stores the record of changes in a structured database, and the changelog files are derived "reports" of the changes. The way we generate reports can be easily updated as needed. With towncrier you only get the generated report in one format and the underlying data are effectively thrown away at the time of report generation.taldcroft commentedon Jan 22, 2021
On the flip side, I do agree that towncrier is conceptually simpler with fewer moving parts.
saimn commentedon Jan 27, 2021
@taldcroft - I agree with you on many points and would love to see a solution to this changelog thing. It's just that if we are doing the change, which in any case has a cost in term of changing habits and procedures and possibly writing helper scripts, I would prefer if we find a solution to this milestone issue.
Well, there is some activity on their repo, with two persons trying to clean some mess with their latest release and planning to do a new one. On the long term it's always hard to say, but probably not worse that many projects we depend on (last release of configobj is from 2014, pyyaml also had many years without real maintenance, etc.).
About supporting what we need with towncrier, I have shown in #10334 (comment) that it already can do what we need, and I also wrote a template to get the same format as we have now for the rendered changelog, so I would be happy to open a PR with that for more discussion.
👍
Indeed, but you have shown with your script that it's easy enough to parse the changelog if we need to convert it to something else ;), and I just used that (thanks!) to do some tests with towncrier.