Skip to main content

ADR-004: Full Adoption of Semantic Versioning for Abyss Web and Mobile

  • Status: Accepted
  • Deciders: Michael White / Chris McCue / Tony Braasch / Willem Paul / Sharan Kandagatla / Scott Houser / Thomas Musengwa / Alex Chen / Marcus Taugner / Richard Plotkin
  • Date: 01/26/24

Context​

Our team currently manages a web framework and a mobile package, released in tandem through a joint process that has been historically aligned. As we look to fully adopt semantic versioning (SemVer), we face the challenge of decoupling the release process for web and mobile due to differing client demands and update schedules. This change will require a new branching workflow, additional testing environments, and updates to our release process and GitHub Actions workflows. Furthermore, we anticipate a potential increase in major version releases, which could vary significantly in scope and impact on consuming teams. This approach is working under the assumption that we will continue to release updates after each 2-week sprint cycle. Unless breaking changes are introduced, most releases will likely remain minor, due to the fact each release typically includes a combination of feature updates and defect fixes.

Decision​

We will move forward with the full adoption of SemVer for our web and mobile packages, releasing them independently to better serve our diverse client base. The adoption of SemVer will involve the following:

  1. New Branching and Release Workflow: We will create separate branching strategies and release workflows for web and mobile to allow for independent versioning and releases.

  2. Testing Environments: Separate web and mobile, test and stage environments will be established to ensure thorough validation of releases for both web and mobile packages.

  3. Communication and Tools: To address potential confusion regarding the scale of changes in major releases, we will enhance our communication strategies and leverage existing tools to help teams understand the impact of each release. We will continue to utilize our change log to provide a clear description of the changes and their impact. Additionally, we will create upgrade guides for major version releases based on the following criteria:

  • Scope of Breaking Changes: If a breaking change affects a critical part of the system that most clients interact with, an upgrade guide will be created.
  • Complexity of Migration: An upgrade guide will be provided when the migration process is non-trivial, involving multiple steps, code changes, or complex configuration updates.
  • Frequency of Use: Changes that impact heavily used features will necessitate the creation of an upgrade guide.
  • Client Feedback: Client feedback indicating past difficulties with upgrades will trigger the production of a guide.
  • Magnitude of Impact: The potential impact of not providing a guide, such as significant downtime or customer dissatisfaction, will require a guide.
  • Version Planning: We aim to group related breaking changes to provide comprehensive upgrade guides less frequently.
  • Industry Benchmarks: We will align our criteria with industry standards and best practices for providing upgrade guides.

The threshold for creating an upgrade guide will be reviewed and adjusted as needed based on client feedback and the evolving complexity of our web and mobile packages.

We will also begin creating a log JSON file that accounts for all breaking changes identified in prior releases and all releases going forward. We will look into incorporating a post install script that will display all breaking changes identified between the previous and newly upgraded version.

  1. Version Maintenance and Patch Strategy: When a new major version is released, critical bug fixes and new features will be applied to the latest version. We will evaluate the need to backport these fixes and new features to previous major versions on a case-by-case basis, considering factors such as the severity of the issue and the number of clients on the older version.

  2. Release Cadence: Our release schedule will continue on a bi-weekly basis, primarily consisting of minor versions that bundle new features with defect fixes. Major versions will be specifically designated for releases that introduce breaking changes. One important note to make is our goal should always be to bundle as many breaking changes together as possible to keep our major releases to a minimum. Patch versions will be deployed primarily for standard releases focused exclusively on defect resolutions without introducing new features. Additionally, patch versions will be expediently issued to address critical defects that demand immediate attention and cannot be deferred to the next scheduled release cycle.

  3. End of Life Plan: We will adopt an end-of-life support plan similar to React's:

    • Active Support: The latest release will receive all bug fixes and new features.
    • Security Support: Critical security fixes will be back-ported to the latest minor release of the previous major versions.

Alternatives Considered​

  1. Continue with the current versioning scheme: This approach minimizes the number of major releases but creates potential risks and confusion when breaking changes are introduced without incrementing the major version.

  2. Batch breaking changes for less frequent major releases: This would involve accumulating breaking changes and releasing them less frequently. However, this approach can delay necessary updates, particularly those related to accessibility, and may result in larger, more disruptive updates for clients.

Consequences​

Positive:

  • Clear communication of breaking changes to clients, leading to better trust and easier upgrade planning.
  • Compliance with industry standards, making our framework more predictable and easier to integrate with.
  • Independent versioning of web and mobile packages allows for more targeted and relevant updates for each platform.
  • An end-of-life plan that ensures continued support for critical fixes.

Negative:

  • Potential initial confusion among clients due to an increase in major version releases.
  • Clients may need to adjust their update processes to accommodate more frequent major version changes.
  • Increased complexity in release management and support processes.
  • Resource allocation to the development of new workflows and tools.

Future Considerations​

  • In a separate ADR address adoption of conventional commits, formal branching strategy (i.e., gitflow) and possible implementation of automated versioning.
  • Monitoring and evaluating the effectiveness of the new release workflow and communication strategies.
  • Refinement of the back-porting strategy for critical bug fixes.
  • Regularly reviewing and updating the end-of-life support plan to ensure it aligns with client needs and industry standards.
  • Investigate and potentially implement automated migration tools to facilitate the upgrade process for clients.

References​

Revision History​

  • 2/14/2024: Added future consideration for automated migration tools and updated, Communication and Tools, section to reduce redundancy and account for addition of breaking changes log file.
  • 2/26/2024: Add future consideration for exploring adoption of conventional commits, formal branching strategy and automated versioning.
Table of Contents