Release notes for RC

[juliasilge]

No rush on this, but I want to start getting feedback on our initial go at release notes for RC and beyond. Some things to note:

• This new file release.md can be slurped up into the product before a release is built, for in-product release notes.
• We could use a strategy like next.md, release.md, and then, say, release-2025-07.md.
• We could work on PRs to next.md during the release, to prep the release notes.
• We would need to finalize the release notes before a release is made but after a branch is cut.
• At a release, next.md can move to release.md and the current release.md can move to something like release-2025-07.md.
• We could keep all the old release notes in the directory together, and make a page where they are available for perusing, linked off from the downloads page.

[netlify]

✅ Deploy Preview for positron-posit-co ready!

Name	Link
🔨 Latest commit	7ffd124
🔍 Latest deploy log	https://app.netlify.com/projects/positron-posit-co/deploys/6865522fbcc6ef000819d582
😎 Deploy Preview	https://deploy-preview-86--positron-posit-co.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[juliasilge]

No rush on these reviews, but @jonvanausdeln @jthomasmock @petetronic can you take a look at these thoughts along with the deploy preview, and share what you think will/won't work for us?

[jonvanausdeln]

This looks good to me. I do like keeping old release notes around, I know users will ask about them and they are handy for QA and issue bisecting. The use of next.md seems reasonable to me. We should think about some GHActions to help automate that transition.

[jonvanausdeln]

LGTM!

[timtmok]

This is what it would look like in Positron:

The editor tab label needs an update to show Positron's version instead of code-oss but that's outside of this PR.

The release notes view is just an editor that renders the markdown and adds in some styling and the Show release notes after an update checkbox. The checkbox location could be moved. It's actually placed at the top for VSCode release notes. We can do the same by adding a # H1 heading. If the viewer sees the H1 heading, then it inserts the checkbox before the rest of the content.

Using release-2025.07.0.md would also be fine during the editing phase. This makes it easier to test the deployment since the release notes URL is constructed using the version. There's no worry about it retrieving the release notes for the wrong version. Also, there's no need to rename files once the release notes are ready.

There's also a command to preview a markdown file as release notes.

Another thing to note: VSCode doesn't publish separate patch release notes. It links to the same file and it's updated to the new commits in the patch. This is also the use case for Show release notes after an update checkbox placement. The display order is H1 with the release heading, the checkbox, and finally the content. It's a nice automatic thing that happens and wouldn't show up on a website.

So we could have something like this:

[juliasilge]

Thank you so much for looking at this, @timtmok! 🙌

• We can't use a first level header in the actual file that goes into our Quarto site, because of how we'll nest the content there. However, we could have a separate .md file that includes this content that does so, maybe eventually automatically generated with Quarto pre-render and include or similar.
• Where should we put such a .md file, that is ready to be used as in-product release notes? Would having it at something like https://raw.githubusercontent.com/posit-dev/positron-website/refs/heads/main/release-notes/release-2025.07.0.md work well? Or would we want to push it to an S3 bucket on every merge here? Other options?

[juliasilge]

Note that we can't use includes with a dynamically generated filename: quarto-dev/quarto-cli#11681

[timtmok]

@juliasilge It's just searching for an element to determine where to put the checkbox. It's a quick change in Positron to use the first h3 element for placing the checkbox. I like it more if the release notes were in one file and we can display it where we need it. Then nothing needs to change here. It would look like this:

Or placing any kind of element that can be found with a HTML document selector would work too.

@petetronic What do you think about placing the release notes in S3? They'll be available through the CDN and that would be the link to use. We have the credentials set up to invalidate the file if we need to update the release notes. Positron itself can build the URL to it using the base update URL (https://cdn.posit.co/positron) from the product.json. This can all be automated in the release process so that the installers and release notes are published at the same time.

[juliasilge]

In e2ec63c I added some of the fancy settings links, so we should confirm that works from within Positron itself. If it's not good, we'll just go back to no fancy links on release notes.

[juliasilge]

@timtmok RE that checkbox:

Or placing any kind of element that can be found with a HTML document selector would work too.

How hard would it be to show up after the highlights section, i.e. before the second H3 header?

[timtmok]

@timtmok RE that checkbox:

Or placing any kind of element that can be found with a HTML document selector would work too.

How hard would it be to show up after the highlights section, i.e. before the second H3 header?

@juliasilge It wouldn't be too hard. I've been thinking it would be best to use an HTML element place the checkbox exactly where we want and be able to see in the markdown where it would go.

[timtmok]

So we could use something like <div id="checkbox"></div> as the placeholder for the checkbox. When release notes load, it normally looks for the first H1 tag but it can be changed to div#checkbox.

[timtmok]

@juliasilge I've updated the Github action to publish the release note. I'll wait for this to merge before merging mine: #97

[Copilot]

Pull Request Overview

This PR introduces initial release notes for the RC release along with a template for future release notes and updates to the download page to include the new notes.

• Adds a new release notes file (release.md) to be used in-product during releases
• Introduces a release notes template (release-notes-template.md) for consistent future entries
• Updates download.qmd and its frozen HTML to integrate the release notes into the installer page

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
release-notes/release.md	New release notes with highlights, changelog, bug fixes, and dependency updates
release-notes/release-notes-template.md	A template for creating future release notes
download.qmd	Adjusted headings and added an include for the new release notes
_freeze/download/execute-results/html.json	Updated hash and pre-rendered markdown content reflecting download page changes

Comments suppressed due to low confidence (1)

release-notes/release.md:46

• It appears the markdown link for issue #7838 is missing a closing bracket. Adding the missing bracket to correctly render the link would improve clarity.

- [[#7838](https://github.com/posit-dev/positron/issues/7838) The Assistant project tree tool now takes parameters to filter the tree output.

[juliasilge]

This PR is now ready for a real review!

• You can see how we'll present the current release notes at: https://deploy-preview-86--positron-posit-co.netlify.app/download.html
• You can see how the release notes will look in the product itself by checking out this branch locally, opening the file release.md, and running the command Developer: Open Current File as Release Notes.

If we can get this reviewed at the beginning of next week (Monday?) then @timtmok can have the markdown ready to go into S3, so it is available when we push the new builds on Wednesday and people start getting them.

cc @jthomasmock

[juliasilge]

OK, I think this is the last of a flurry of PRs for our FIRST STABLE RELEASE! 🥳

[jonvanausdeln]

LGTM!