Release process for subgraphs

General Ecosystem Updates
1

Introduction

In order to guarantee the quality of the releases and prevent potential issues stemming from our current rollout procedure, we’ll be detailing the steps required to be done in order to ensure any release is handled properly.
This set of guidelines has been part of the corrective measures detailed in the Core Network Subgraph v0.23.0 Upgrade Post-Mortem (Jan 23rd)

Decision flowchart

release-process|100%
release-process|100%747×1424 71.2 KB

Release note requirements

Release notes must contain:

  • Comprehensive list of changes
  • Detailed description of bugs fixed
  • Deprecation notices, if needed
  • Clear notice of any breaking changes

While accumulating changes in staging, release note drafts must be merged with the currently accumulated release note for the staging environment (resets when pushing to the main branch and releasing)

Rollout procedures specifics

The rollout procedures for breaking changes ensure we can lead users to orderly migrate to the latest update without causing any issues on their apps.

We are currently proposing 2 different procedures, as we slowly transition from hosted service as the canonical endpoint for network data consumption, towards using the network, taking into consideration how both of those products work and how to best approach versioning in each of them.

Both procedures are going to be run in parallel for as long as the transition from hosted service to the decentralized network takes, and they are both compatible with one another, so no need to worry there!

For the hosted service version, this is gonna be the expected rollout procedure:

  • Announcing a breaking change is happening
  • Providing a separate endpoint with the changes already live (staging) for users to migrate over to as well as release notes
  • Giving N days for them to migrate to the separate endpoint
  • Releasing safely to the production endpoint
  • Announcing the update of the production endpoint
  • Giving M days for users to migrate back to the production endpoint

While for the decentralized network version, the rollout procedure looks a little different, due to how the network allows us to better version our releases:

  • Announcing a breaking change is happening
  • Provide release notes
  • Giving N days for them to modify the endpoint from a subgraph endpoint to a specific deployment endpoint
  • Releasing the new version safely to production
  • Announcing the release of the new version to production
  • Users are now able to move to the new version of the subgraph whenever their apps are ready to do so (no time limit imposed here, but the old version might slowly start to lose indexer support over time)

Hosted service vs Decentralized network procedure considerations

In both procedures, there’s gonna be a time period (N) where apps need to introduce changes in order to not break. For the hosted service version, this is gonna require the app to fully support the breaking change before that time period expires, while for the decentralized network version, the app will merely have to ensure they are specifying their endpoint to consume the deployment data directly.

After the release to production, anyone using the hosted service versions will just need to point to the production endpoint again, while decentralized network version users will be able to release their new versions with support for the changes whenever they choose to do so.

By doing so, we are providing ways for users to seamlessly upgrade their apps without having any downtime, as long as they do so within our migration window if they are using hosted, or as long as indexer support remains for the old version.

Migration window considerations

The migration window (time interval, modified through N and M) will vary on a case by case basis, depending on the urgency of the release, and the effort required to migrate.

We think that the minimum values for N and M should be 1 day each, to accommodate for more urgent releases while still allowing any timezone to be able to see the announcement before it goes live, but for most releases we expect both of these values to be higher (closer to a week if possible).

We also make sure all the information that our users might require in order to migrate to newer versions is available, as well as any information about the changes themselves.

When the beginning of a rollout procedure is announced, merging to staging will be avoided for any new breaking changes, as it would affect the migration process.

Once the end of the rollout procedure is announced, breaking changes can be merged into staging again.

Announcement details

For the rollout procedures, it’s necessary to define the exact channels where announcements are going to be happening.
We propose the following:

For the content of the announcement on Discord, we must include:

  • N and M values to be used for the rollout procedure (i.e. explicitly state the migration window)
  • Explicitly state the beginning or end of the rollout procedure
  • Explicitly state the versions/endpoints to be used during the migration window
  • Link to release notes
8 Likes