SPEC 10: Add an initial draft for a SPEC about release documentation #321
Conversation
|
|
||
| TO DO | ||
|
|
||
| ### Automation |
There was a problem hiding this comment.
actions to be used by either towncrier systems or by direct edits of a single changelog file (both approaches have legitime use cases):
https://github.com/scientific-python/action-towncrier-changelog
https://github.com/scientific-python/action-check-changelogfile
There was a problem hiding this comment.
quasi-automation: I do run cosistency checking scripts before cutting a release to ensure all PRs in a release either have a changelog, or e.g. a no-changelog-required label. So in my mind the actions are required for the PR, but in practice there is always some inconsistencies, especially when there are many people doing merges with significantly different level of tolerance towards failing CI checks.
There was a problem hiding this comment.
I think it would be useful to gather info from projects which use more niche workflows (like SciPy) on what stops them from moving to an automated tool, to help guide readers. There is generic dev workflow churn, but any other reasons are probably more informative.
There was a problem hiding this comment.
@lucascolley Yes, there are always exemptions. Could you point me to the SciPy documentation that covers this part?
There was a problem hiding this comment.
There is a bit of documentation at https://scipy.github.io/devdocs/dev/core-dev/index.html#release-notes. We recently also introduced a "needs-release-note" tag to try to reduce the chance that PRs are missed.
|
|
||
| ### Automation | ||
|
|
||
| TO DO |
There was a problem hiding this comment.
I would recommend adding a link to the PyPI instructions for automation here: https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
There was a problem hiding this comment.
but this document is not about releasing, but just the changelog, and thus automation for me means e.g. the github actions checking the existence of a changelog, or the changelog framework itself, e.g. creating one single changelog file from the fragments for towncrier
There was a problem hiding this comment.
In my mind, generating the changelog and the release are tightly coupled and usually happens at the same time, so for any automation to happen it would be in the same file. here is an example of an automated release pipeline generated with the above docs that also generates release notes automatically: https://github.com/duckdb/dbt-duckdb/blob/master/.github/workflows/release.yml
There is also a --notes tag that lets you add custom (generated or manually entered) notes
There was a problem hiding this comment.
I like to have the changelog available, and complete/correct during the dev process already, it's quite useful for big projects, but I also find it somewhat useful to enforce the presence the changelog at the time a contribution is made
spec-0010/index.md
Outdated
| - maintaining accuracy of the records about the changes in each release (e.g., | ||
| adding essential information that was left out when the initial changelog was published) | ||
| - improving clarity and readability of the change log. Try to avoid nitpicking when | ||
| making edits to the changelog. |
There was a problem hiding this comment.
Slightly related and not sure myself: should changelogs link to API like functions etc when rendered by sphinx? This can be very nice from a user perspective but over time, these references tend to get stale pretty fast due to deprecations, etc. We should probably mention this trade-off in some capacity.
There was a problem hiding this comment.
Yes, for that reason, astropy no longer put "live" links (especially intersphinx stuff) in changelog, so we don't have to go back and fix broken links N number of years later, and thus changing history (and if you type at 88mph, more bad things might also happen). Some URLs still snuck in and we handle those as need arise. Our decision had oppositions, so it is not perfect solution either.
spec-0010/index.md
Outdated
| ### Editing a Changelog | ||
|
|
||
| It is generally acceptable to edit a changelog for the following reasons: | ||
| - maintaining accuracy of the records about the changes in each release (e.g., |
There was a problem hiding this comment.
We use nitpicky so any sphinx links in our changelog can often break with new releases. So that is a very common reason to edit our changelog.
There was a problem hiding this comment.
Does "maintaining accuracy" include fixing typo?
|
|
||
| ## Notes | ||
|
|
||
| <!-- |
There was a problem hiding this comment.
Another thing @InessaPawson and I chatted about is to provide a template for a GitHub profile readme that shows OSS/Scientific Python contributions:
https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/managing-your-profile-readme
There was a problem hiding this comment.
@guenp After giving it more thought, I wonder if this info belongs to the SPEC about release documentation. I will keep the conversation open to gather feedack from others.
InessaPawson
changed the title
| - **Security**: Vulnerability fixes. | ||
|
|
||
| ### Standard Changelog Format | ||
| There is not one standard changelog format. |
There was a problem hiding this comment.
Should at least list some that are recommended (and give reasons why they are recommended)?
|
pre-commit.ci autofix |
|
Should there also be a section about "when you should not put things in change log"? |
InessaPawson
changed the title
InessaPawson
changed the title
Co-authored-by: Lars Grüter <[email protected]>
Co-authored-by: P. L. Lim <[email protected]>
|
pre-commit.ci autofix |
InessaPawson
changed the title
InessaPawson
changed the title
Fix #242