How to share release notes on website

[juliasilge]

We've got a very initial downloads page on our website here: https://positron.posit.co/download

One next step we need to take is to make release notes available on our website. Take a look at some different ways we might approach this:

• One long running page, with each release a heading
• Separate markdown files per release, using the markdown for the current release on the main downloads page and keeping the rest of the older markdown files around but honestly not super easily navigable
• Separate pages per release and easily navigable, but not surfaced on the main downloads page
• Another example with one long running page, but broken out so you click to older content (and cute emoji use!)

Side note: I am noticing the big "download" button in the navbar on the VS Code docs site and like that a lot.

[juliasilge]

We are planning for not-very-automated release notes because we prefer for these to be more like a blog post (in fact, we would use it as a starting point for actual blog posts) and less like a list of issue titles as bullets.

[atheriel]

Tom tipped me off to this. Our experience with the pro products indicates that a surprising number of internal and external folks do read release notes, and few of them would be well-served by the "list of issue titles as bullets" approach. I'd be very happy to see Positron have narrative and end-user-friendly release notes, though I know that is this much more work!

[timtmok]

Keeping a separate markdown file for each release would be my preference. Each monthly release gets its own file (1.95, 1.96, etc.) and the version is used in the link to it.

Doing it this way makes it easy to display the release notes in Positron. All the code for displaying release notes currently checks VS Code's server that hosts the release notes. The infrastructure is there for the "Show Release Notes" action to display a markdown file. What needs to change is where it gets the markdown file and how it compares versions to decide if an update just occurred.

The release notes viewer is also quite capable of showing blog style content. Images are easy to embed and linking it relative to the markdown file is all that's required. Video is also supported if we need it (VS Code uses mp4 files).