Skip to main content

Separate Versioning for Abyss Mobile and Web Packages

  • Status: Proposed
  • Deciders: Abyss Team
  • Date: 2025-07-01

Context​

Currently, our Abyss web (+ core, api, parcels) and mobile packages live in the same monorepo and share the same version number. They are released together through a joint process using Lerna, with both packages incrementing to the same version (typically a minor release) during each release cycle. The documentation site also references this shared version in its versioning system.

As the project evolves, there is a growing need to decouple the versioning of the mobile and web packages to allow for independent development cycles and versioning schemes. This need is particularly important for major releases where development timelines may not align between the platforms.

Our existing process works as follows:

  • Both abyss-web and abyss-mobile packages are housed in a monorepo
  • Release branches are cut from main with naming convention release/v{version}
  • Lerna is used to publish all packages simultaneously with the same version number
  • The documentation site (using Docusaurus) is deployed with version-specific URLs that reference this shared version
  • Version dropdown in the docs site relies on a shared version between web and mobile components

While we've already implemented versioned documentation through the docs-web-release-versioned.yml workflow, the current approach assumes a shared version between mobile and web packages.

Decision​

At the appropriate time we will move forward with implementing separate versioning for the Abyss web and mobile packages while maintaining them in the monorepo. This approach allows for independent version increments while preserving the benefits of our monorepo structure, with the critical condition that releases will continue to happen simultaneously for all packages.

Key aspects of this decision:

  • Package version numbers can diverge (e.g., web at v2.10.0 while mobile at v3.0.0)
  • The release process will remain synchronized (packages released together)
  • All packages will continue to share the same release branches and deployment workflows
  • Only the version numbers themselves will be decoupled, not the release timing

If release timing needs to diverge in the future (e.g., web and mobile on completely different release schedules), we would need to adopt the alternative approach of separate repositories.

Important Note: While this is our chosen strategy, we will not be implementing this change immediately. Currently, both web and mobile packages are able to release the newest major release (v2) together. This ADR documents the approach we will take when the time comes that version divergence becomes necessary.

Implementation Details​

  1. Package Versioning and Release Branch Naming

    • Each package (abyss-web and abyss-mobile) will maintain its own version in its respective package.json file
      • Note: abyss-core will follow abyss-web versioning since mobile only uses it internally for lint, prettier, and babel.
    • Release branch naming will change from release/v{version} to release/{year}.{month}.{release-number} using Calendar-Based Versioning (CalVer):
      • year is the four-digit year (e.g., 2025)
      • month is the two-digit month (e.g., 07 for July)
      • release-number is an incrementing number within that month (starting at 1)
      • Example: release/2025.07.1 for the first release in July 2025
    • This naming convention removes the dependency on a shared version number while providing a clear, chronological ordering.

  2. Updated Lerna Configuration

    • Lerna will be configured to respect the individual package versions when publishing
    • The publish workflow will be updated to handle independent versioning through the --no-version-updates flag or appropriate configuration

  3. Documentation Site Versioning

    • The versioned documentation deployment process will be updated to accommodate separate versions
    • A new folder structure in the S3 bucket will be implemented using CalVer: 
      s3://abyss-web/releases/{year}.{month}.{release-number}/
      ├── web/{web-version}/
      └── mobile/{mobile-version}/
    • Example: s3://abyss-web/releases/2025.07.1/
    • This structure allows for a unified identifier based on CalVer while preserving specific version information

  4. Version Dropdown UI

    • The version dropdown component will no longer be shared between web and mobile but instead will have separate instances for web and mobile
    • The versions.json file will be enhanced to include mappings between release identifiers and specific package versions: 
      {
        "latestRelease": "2025.07.1",
        "releases": [
          {
            "id": "2025.07.1",
            "web": "v2.3.0",
            "mobile": "v2.1.0"
          },
          {
            "id": "2025.06.1",
            "web": "v2.2.0",
            "mobile": "v2.0.0"
          }
        ]
      }
    • The PackageVersionLink.jsx component will be updated to display the appropriate version based on the documentation context (web or mobile)

  5. Workflow Updates

    • The abyss-create-release.yml and associated workflows will be updated to:
      • Use CalVer-based branch naming
      • Allow selective version increments for web and mobile packages
    • The abyss-publish.yml and associated workflows will continue to use Lerna but with configurations to respect individual package versions
    • Versioned documentation workflows will be updated to accommodate the new folder structure and version mapping

  6. Git Tag Management

    • Git tags will follow the same CalVer format as release branches: release/{year}.{month}.{release-number}
    • Each tag will include an annotation that captures the specific versions of each package: 
      Release {year}.{month}.{release-number} - web@v{web-version}, mobile@v{mobile-version}
    • Example: Release 2025.07.1 - web@v2.3.0, mobile@v2.1.0 (for now, it will be assumed that api, core and parcels will follow the same version as web)
    • This approach maintains a clean, consistent tag naming convention while preserving complete version information in the tag annotation
    • Tags can be created in CI/CD with: 
      git tag -a "release/2025.07.1" -m "Release 2025.07.1 - web@v2.3.0, mobile@v2.1.0"
    • Tag details can be viewed with: git show release/2025.07.1

Alternatives Considered​

Split Repositories and Completely Independent Releases​

Advantages:

  • Complete independence in development and release cycles
  • Simplified versioning within each repository
  • Clearer separation of concerns

Disadvantages:

  • Loss of monorepo benefits
  • Need to create and maintain a separate shared repository for common code
  • Significant rework of CI/CD pipelines
  • Complex documentation integration requiring micro-frontend approach
  • Higher maintenance overhead and coordination for shared resources

Consequences​

Positive​

  • Independent versioning allows teams to release updates according to their own schedules
  • More precise semantic versioning for each package as outlined in ADR-004, allowing version numbers to accurately reflect the nature of changes in each package
  • Documentation site can still provide a unified experience while displaying correct version information
  • Monorepo structure continues to provide collaboration and code-sharing benefits

Negative​

  • Increased complexity in release management and branching strategy
  • Additional maintenance required for the documentation site version handling
  • Potential for confusion when communicating about releases without a shared version number

Future Considerations​

  • Evaluate the effectiveness of Calendar-Based Versioning (CalVer) for release identifiers and adjust as needed
  • Consider implementing automated tooling to manage the relationship between releases and their component versions
  • Monitor the complexity of managing multiple versions and assess if further decoupling (separate repositories) might be beneficial in the future
  • Explore enhanced UI options for the documentation site to better communicate the versioning relationship between web and mobile
  • Consider implementing version-specific API compatibility checks to ensure that shared dependencies work correctly across different version combinations

References​

Table of Contents