DOC: Add release notes and update documentation infrastructure#2534
DOC: Add release notes and update documentation infrastructure#2534blowekamp merged 1 commit intoSimpleITK:mainfrom
Conversation
blowekamp
commented
Mar 19, 2026
- Add 56 release note files (v0.7.0 through v3.0.0a3) to docs/source/releases/
- Add docs/source/releases/index.rst toctree for all releases
- Update docs/source/index.rst to include releases in table of contents
- Update docs/source/conf.py to enable myst_parser for Markdown support
- Add Utilities/Maintenance/DownloadReleaseNotes.sh to fetch release notes from GitHub via gh CLI; saves notes-{tag}.md with cleaned-up formatting
- Update .pre-commit-config.yaml to exclude docs/source/releases/ from the comment spell checker
|
There are a few section in the notes that I am not sure should be there. I already removed the empty anchors/links. There are also the older explicit links to source forge download. And in the newer notes, there is the automatically generated "What's changed" sections that include links to all the PRs merged. Also currently there is not link to the GH tag/release. |
zivy
left a comment
There was a problem hiding this comment.
Looks good.
Possible changes (not 100% sure these are improvements):
- Change directory name from "releases" to "release_notes".
- The current data flow path seems to be that (1) a release with notes is created on GitHub and then the (2) notes are downloaded from GitHub using the
DownloadReleaseNotes.shscript and added to the repository.
An alternative data flow path that I used here is to (1) write the release notes as markdown and add to the repository. (2) When a tag is pushed to the repository the contents of the release notes file are automatically added to the GitHub release.
I think the second option is easier to automate, but possibly the first is too?
|
The script is what was used to get these release note. How to do release notes in the future is a different issue. My concerns were about the contents of these note files, which was not addressed in your comment. Can you please comment on my concerns about the contents of the note files? |
|
I am not concerned with broken links in the release notes. As time goes by those will happen and it isn't worth the effort to go back and remove or modify URLs. The links are relevant and of interest at the time of the release or shortly thereafter. I view it as a snapshot with a limited shelf life. An extended shelf life requires no usage of links. |
e127e3c to
961e0e2
Compare
- Add 56 release note files (v0.7.0 through v3.0.0a3) to
docs/source/release_notes/
- Add docs/source/releases/index.rst toctree for all releases
- Update docs/source/index.rst to include releases in table of contents
- Update docs/source/conf.py to enable myst_parser for Markdown support
- Add Utilities/Maintenance/DownloadReleaseNotes.sh to fetch release notes
from GitHub via gh CLI; saves notes-{tag}.md with cleaned-up formatting
- Update .pre-commit-config.yaml to exclude docs/source/release_notes from
the comment spell checker
- Remove stand alone SourceForge links
961e0e2 to
4ef81c0
Compare
zivy
left a comment
There was a problem hiding this comment.
Looks good.
Interesting to see how the style changes over time. A significant change starting with release 2.4.1 uses GitHub's automatically generated release notes with the "What's Changed" section that lists the commit header. Makes it a bit lengthy and detailed but the headers are reasonably informative so not a problem.