Skip to main content

Assets CDN Versioning Implementation

  • Status: Proposed
  • Author: Tony Braasch
  • Deciders: Abyss Team
  • Date: 10/4/24

Context​

Both the Abyss web and mobile libraries rely on assets hosted on our abyss-cloud CDN. These assets include icons, images, and fonts. Historically, we have not versioned our CDN, leading to direct overwrites with each deployment. This lack of versioning restricts our ability to update asset structures or CDN paths without causing breaking changes for existing versions of our components.

Decision​

We have decided to implement versioning for our CDN assets. This will allow us to make necessary structural changes to the assets and their referencing paths in our components without affecting the current implementations in use by consuming teams.

Reasons for Decision​

  • Avoid Breaking Changes: Versioning the CDN allows us to update assets and modify file structures without impacting existing users of the library.
  • Facilitate Continuous Development: With versioned assets, we can continuously develop and improve our asset library.
  • Best Practices: Versioning is a best practice for asset management, especially in scalable and evolving projects, ensuring reliability and clarity in dependency management.

Implementation​

  1. Create Assets Release Pipeline: Introduced in abyss-create-assets-release.yml, this pipeline, similar to abyss-create-release, handles version bumping for abyss-assets based on major/minor/patch selections and creates a corresponding release branch.
  2. Updated Deployment Workflows:
    • assets-integrate.yml: Modified to pull the package version from abyss-assets and append it to the S3 bucket path upon changes to the release branch. Will automatically run when assets changes are pushed to an assets release branch.
    • assets-release.yml: Requires manual trigger for deployment to ensure controlled releases. Integrated with the versioning system to append version to the S3 bucket path.
  3. Central Management of CDN URL: Implemented in getCdnUrl.js for web to centralize the management of CDN URLs, thus easing updates and maintenance. Something similar still needs to be implemented within mobile.
  4. Version Initialization: Starting the abyss-assets package version at 1.0.0, decoupling it from the versioning of web and mobile components.
  5. Prepublish Script Modification: Updated the build script to replace the ABYSS_ASSETS_VERSION environment variable during the bundling process, ensuring components use the correct CDN version.
  6. Documentation Update: docusaurus.config.js uses webpack's DefinePlugin to replace the ABYSS_ASSETS_VERSION during the build, aligning documentation with the current CDN version.

Future Considerations​

  • Mapping File: Post-release, consider creating a changelog or mapping file that correlates the versions of abyss-web and abyss-mobile with abyss-assets versions to maintain clarity and ease troubleshooting.

Consequences​

Pros​

  1. Enables flexible and non-disruptive updates to assets.
  2. Prevents breaking changes for existing users when assets are updated.
  3. Aligns with best practices for managing static assets in software development.

Cons​

  1. Requires additional management and oversight to maintain version synchronicity across different components and their dependencies.

Alternatives Considered​

  1. Single Version Lifecycle: Continue with the unversioned approach. Rejected due to high risk of breaking changes and inflexibility.

References​

Revision History​

  • 10/4/2024: Initial draft
Table of Contents