CDS Release Practices #761
Locked
cb-ekuersch
announced in
Announcements
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
TL;DR / Summary
CDS version 9 will be released as originally scheduled, in early Q2. Version 9 primarily focuses on modernizing CDS’ peer dependencies (React, React Native & native deps) and contains minimal breaking API changes; adoption is expected to be rapid without the need for customer teams’ support.
Following CDS 9, a few impactful changes are planned for the team’s release practices:
the rigid release cadence of 2 major versions a year (H1/H2) will be discontinued, saving major releases for intentional/strategic moments planned by the team and communicated clearly, ahead of time, up to one quarter prior to release
all major version releases will target a -1 version compatibility, meaning v10 will have 0 breaking API changes relative to v9 and so on
visual changes will be allowed to release more often, in routine minor version updates, increasing the velocity of meaningful design system improvements
migrations will shift from a reactive remediation approach to a proactive one, potentially removing the necessity for migration scripts at the time of release. Proactive migrations will have the ability to be executed
the CDS team will facilitate upgrades when necessary to keep customer teams focused on the product
Release Practices
Patch and Minor Versions
CDS will maintain a continuous delivery approach for patch and minor versions, shipping fixes and new features multiple times per week.
Visual/Design Changes {#visual/design-changes}
Historically, CDS has been overly cautious around releasing changes that could alter the visual appearance of consumers’ UIs. This has limited the team’s velocity and put extra emphasis and stress on major version releases. In order to unblock key design updates and increase release velocity, CDS will update its policy for these kinds of changes: Any change that affects the appearance of a component will be allowed to release as a minor version update. There are some subtle exceptions to the rule, outlined at the bottom of the section. To improve visibility and simplify regression testing for custom CDS themes, the CDS team may introduce specialized tooling designed to help customers evaluate the impact of these updates.
The semver spec does not cover visual changes and other open source component libraries have not come to a consensus for how to address these scenarios. Libraries such as MUI permit small CSS changes that have “low probability of negatively impacting your UI”; other libraries' policies are similarly vague. One thing all the libraries do agree on is that breaking consuming apps’ layouts is bad. As an example, maintainers have been scrutinized for removing default margin in a minor release, leading to pressure to revert the change.
Acceptable visual changes in CDS
Visual changes held for a major CDS release
Component Release Velocity
CDS components are surprisingly complex. A proper CDS component is:
Releasing a new component that satisfies all of the above takes time. CDS currently approaches new components with an all or nothing mentality when it comes to release. We can compromise on a few of the bullet points above to get limited versions of new components out to customers faster and follow up with a more iterative approach than was seen in the past. The goal will be to get customer feedback quicker without sacrificing its ability to iterate on the component’s design, API or overall quality.
Major Versions
CDS will drop its arbitrary two major releases a year policy and save major releases for planned, strategic moments for the product. A single major version is still expected to release each year, although that is not an official commitment. The reduction in frequency of major releases is made possible largely by the team's shifted stance towards releasing visual changes.
CDS’ goal for every future major release is to ensure a near-effortless upgrade experience, with minimal to no breaking changes relative to the previous major version (e.g., a smooth upgrade path from v9 to v10, though breaking changes are expected from v9 to v11). Upgrades from one major version to the next will land in a single PR.
To achieve this, CDS will commit to the following practices:
🤏 Minimizing Breaking Changes
Breaking Changes are Exception, not Expectation
A typical major release will introduce new deprecations, add new advanced functionality and remove APIs that have been deprecated for one full CDS version cycle.
CDS will no longer release major updates containing breaking API changes unless absolutely necessary or for strategic/operational reasons. Such exceptions may include required internal dependency upgrades (e.g., React) that affect CDS component interfaces, or strategic initiatives that unblock high-priority company initiatives or that drop support for older features due to security concerns.
Predictable Deprecation Process
💬 Crystal Clear Communication
RFC / Announcement (pre-upgrade) {#rfc-/-announcement-(pre-upgrade)}
CDS will publish an RFC with the changes it’s committed to release in the next major version. This announcement will be made far ahead of the anticipated release date, up to one quarter prior to release. In order to not ignore any open source consumers, this announcement will be posted as a GitHub discussion and shared internally via Slack. This should be a collaborative moment and feedback regarding the nature and scope of the proposed changes will be welcome.
Improved Communication Hub (post-upgrade)
CDS will create a standardized Slack channel to serve as a communication hub during active major version upgrades. It will be utilized to:
CDS Upgrade Calendar
When performing white-gloved migrations on customer repos, CDS will share its upgrade schedule via a shared Google calendar as other successful Coinbase migrations have done.
Documentation
Upgrade guides as well as roadmaps (even major release RFCs) will be published to the CDS docsite for easy, self-service access
🔧 Customer Readiness and Support
Proactive Migration Paths
When a new deprecation is introduced, migration paths (scripts and/or agents) will be immediately (or shortly thereafter) available to use. This will allow apps to proactively address deprecated CDS exports before their pending removal in the upcoming version.
Upgrade Readiness Metrics
CDS will establish automated jobs to collect and report metrics on customers’ "readiness" to upgrade CDS to the next major version, after it is announced. This can be gauged by measuring the number of deprecations still present in the consumer’s code. Proactive migration scripts (see above) can be used to remedy these situations and better prepare the customer for the upcoming release.
Automated Migrator Agents
CDS will utilize the CB-AGENT platform to create automated agents capable of performing upgrades in the background and in parallel to assist in the rapid adoption of new versions.
Service Level Agreement (SLA)
CDS engineers will commit to an SLA to assist in resolving any bugs or visual regressions that appear within one month after a major version upgrade. Beyond that timeframe, customers will be expected to report issues through the usual communication channels (i.e. #ask-cds).
Upgrade Responsibility
The initial upgrade to the new major version falls to the CDS team. Responsibility for handling deprecations and consuming proactive migration tools rests with the customer teams.
Long-Term Support (LTS)
After a major release, the prior version series will continue receiving relevant bugfixes until it reaches its end of life at the onset of the following major version (8.x will receive patches until 10.x is released). In the past, this practice was only occasionally performed for high-priority fixes (i.e. incidents) and never recognized as an official release practice, until now. This change in practice should put less pressure and urgency on major upgrades following a new release.
Mobile Runtime Policy
The Coinbase Mobile Runtime (CMR) is a project that maintains Coinbase’s complex React Native and Expo dependencies, several of which overlap with CDS’s own peer dependencies*.* CMR matches Expo’s SDK releases of 3 releases every year. Following a new CMR version, consumers such as consumer/react-native are subsequently upgraded.
Upon the most recent release of CMR, the dependencies shared between CMR and CDS had drifted quite far apart (react-native 0.74 recommended by CDS; 0.81 in CMR v7). Luckily cds-mobile successfully built with the newer react-native version despite what was set in its peer dependencies. If it had not, that would have been a huge blocker, preventing consumer/react-native from receiving important react-native updates.
Going forward, CDS will release new versions following every CMR release. In most cases this will not need to be a major release containing breaking changes since CMR mainly bumps react-native and other mobile dependency versions.
When upgrading to the latest CMR, CDS will:
Component Performance Testing
Historically, component performance testing has been limited to specific components and implemented on an as-needed basis. CDS is looking into an expansion of its investment into performance testing in order to prevent regressions on every release.
All reactions