Open anaelleltd opened 1 month ago
Please share your suggestions or recommendations so that the document above can be made as comprehensive as possible.
Some suggestions:
Thank you for these clarifications and corrections, @joepetrowski. I have included them in the main document.
One thing that I discussed today with @eskimor is the introduction of some sort of "metadata diff tool". This should help with informing people if for example storage items change. This tool could run for each pr merged to main and later for the release itself. There should exists "client" that can read these diffs and find out if a storage item that your app is using while change. By doing it per pull request the teams could get notified before the actual release is happening. The teams would need to run this tool maybe once per night to get notified.
@josepot you are already generating interfaces for the runtimes using metadata, not sure if you could maybe easily figure out what apis a user is using and based on this determine the storage item.
@josepot you are already generating interfaces for the runtimes using metadata,
yes, of course! All of the generated code comes directly from the metadata.
not sure if you could maybe easily figure out what apis a user is using and based on this determine the storage item.
In a way our type system already does this for our users, because if the types generated from the next runtime don't match, then the typescript compiler will let our users know what has changed.
One thing that I discussed today with @eskimor is the introduction of some sort of "metadata diff tool". This should help with informing people if for example storage items change
We could easily use the tools that we have built to generate a diff tool like this. We have already built similar tools that we use internally to detect common types across different chains, so that we can give them some friendly names for the developers.
So, yeah, we could totally build a "metadata diff tool", for sure! How urgent/important is this?
The teams would need to run this tool maybe once per night to get notified.
Wouldn't it be possible/desirable to use chopsticks to get the resulting metadata that will take place after a certain referenda gets enacted, and then run the diff tool against the resulting metadatas of those referendas? 🤔
So, yeah, we could totally build a "metadata diff tool", for sure! How urgent/important is this?
Not a requirement that you write it. The general idea here would also be that teams are informed before the stuff is on chain, so the apps do not break in production. Better they are informed before, make the code work with both version and then be ready when the runtime upgrade is live.
We also should highlight breaking changes more prominently in the changelogs. Basically it should be easier to find out when a change breaks something, like https://github.com/polkadot-fellows/runtimes/pull/337 which was made not clear that it breaks the transaction encoding.
We should start simple by including the following information in the changelog:
We should create multiple communication channels for pushing information around upcoming releases. When we are aware that breaking changes will hit a release, we should start to push out information and the closer we get to the actual enactment of the update the more spammy we should get. Better to over deliver and to annoy people, than people to miss the information. We should support Element, TG, email, github, maybe more? A release calendar.
Thanks 👍🏻 I would maybe add that linking to PRs and showing off the integration tests that changed in the breaking change PRs will get a long way to quickly evaluate the required effort. Alternatively tips like -> Update your .js libs would help. Having calendar to see it visually would be epic.
@bkchr @jak-pan @SBalaguer I have summarised the requirements for a runtime release calendar here Please let me know if I missed anything important.
Overview:
This document aims to summarise proposed/existing options for formalising the process by which:
Considerations:
Strategies:
Note: A ☑ indicates that the item is already In Progress.
Contributors:
Contacts:
This table can be edited & copied/pasted as a comment on scheduled runtime upgrades to ensure that relevant teams are contacted based on proposed/queued PRs. The contact details for each team are available here.
Last updated: 2nd July 2024