search

stellar / rs-soroban-sdk

Rust SDK for Soroban contracts.
Apache License 2.0
125 stars 67 forks source link

Create migration notes in Rust docs for v22 #1248

Open leighmcculloch opened 6 months ago

leighmcculloch commented 6 months ago

What

Add migration notes for v22.

Why

To make the most of docs.rs to provide more complete and thorough migration notes that have not only textual descriptions, but examples and working code that can be tested.

This change adds a GitHub Actions workflow that checks that for any new releases we are preparing, that the migration notes are added.

Close #1048

sisuresh commented 6 months ago

So in the release workflow, a PR like https://github.com/stellar/rs-soroban-sdk/pull/1244 will catch the missing notes, and then we'd add it in that PR?

leighmcculloch commented 6 months ago

Yup, that's correct. The job will error indicating that the release notes need writing.

leighmcculloch commented 6 months ago

I think it's also reasonable for us to go the simpler route of making the release notes part of the GitHub Release. If we want to include working examples in the release notes then the Rust docs will help us do that in a reliable way.

leighmcculloch commented 3 months ago

I missed getting this change in before the last release, and reflecting on this I'm not convinced we're going to be able to maintain keeping this updated and doing it before every release which is an annoying requirement because the release notes get snapshotted at the point in time the tag is made.

Closing because while it seemed like a nice idea I don't expect we'll be able to execute it very well.

We should stick to GitHub release notes, and where-possible include working examples inside the Rust docs (as we do today) for any new feature or changing feature, along with using the rust deprecated annotations that will help folks get to where they need to be via compiler warnings when they're using something that is being replaced with something new.

leighmcculloch commented 3 months ago

Reopening because it occurred to me that why-not-both. We can do release notes on GitHub releases as we do for the simple release flow, and have a _migrations section of the rust docs dedicated to just breaking changes.

This is more similar to what @ueco-jb suggested in https://github.com/stellar/rs-soroban-sdk/issues/1048.