Release Management

Documentation for Release Management in the EigenLayer-AVS system.

Purpose and Scope#

This document outlines the release management process for the AVA SDK JS repository. It covers the automated versioning system, how changes are tracked, the process of creating releases, and the tools used to manage this lifecycle. For information about the continuous integration pipeline, see CI/CD Pipeline.

Overview of Release Management System#

The AVA SDK JS repository uses a structured release management process based on the Changesets tool. This system automates version bumping, changelog generation, and GitHub release creation while maintaining a clear history of changes.

Sources:

Versioning Strategy#

The AVA SDK JS follows Semantic Versioning (SemVer) principles, with version numbers in the format of MAJOR.MINOR.PATCH:

  • Major version: Breaking changes that require significant adjustments by consumers
  • Minor version: New features added in a backward-compatible manner
  • Patch version: Backward-compatible bug fixes

This versioning strategy is implemented using Changesets, which allows developers to indicate the impact level of their changes.

Sources:

Changesets Tool Configuration#

The Changesets tool is configured to manage version tracking and changelog generation. The configuration specifies:

SettingValueDescription
changelog"@changesets/cli/changelog"Module used to generate changelog entries
committrueAutomatically commit version changes
access"restricted"Package access level (private by default)
baseBranch"main"The branch from which changesets are calculated
updateInternalDependencies"patch"How to handle updates to internal dependencies

Sources:

Change Recording Process#

Before changes can be released, they must be documented using changesets. The repository implements an automated workflow to standardize this process.

Sources:

The recording process includes:

  1. A developer triggers the "Record Changeset" workflow, specifying the change type
  2. The workflow creates a properly formatted changeset file in the .changeset directory
  3. The changeset is committed to a new branch and a pull request is created
  4. When merged, this changeset will be used in the next release process

Key steps in the workflow include:

Release Creation Process#

When it's time to create a new release, the process is automated through a GitHub workflow that processes all accumulated changesets.

Sources:

The release creation process includes:

  1. A developer triggers the "Create Release" workflow on the main branch

  2. The workflow runs the Changesets versioning command to:

    • Update package versions based on the accumulated changesets
    • Update the CHANGELOG.md file with the changes
    • Remove the changeset files

  3. The changes are committed and pushed to the main branch

  4. If a version increment is detected, a GitHub release is created

Key steps in the workflow include:

Changelog Management#

The CHANGELOG.md file contains a structured history of all releases. Each version section includes:

  1. The version number as a header
  2. Subsections for "Minor Changes" and "Patch Changes"
  3. Bullet points describing individual changes with references to commit IDs

Example from the changelog:

## 0.7.1

### Patch Changes

- 10801d8: Updated README.md with release instructions
- ec7427c: Make sure COMMIT_MESSAGE is written into changeset
- 5f9dfc3: hi there

Sources:

The changelog is automatically updated during the release process, using content from the changeset files. This ensures that all documented changes are included in the release notes.

Manual Release Process#

In addition to the automated workflows, developers can perform a manual release if needed. The typical steps for this process are:

  1. Ensure all desired changes are on the main branch
  2. Create and merge changesets for any undocumented changes
  3. Run npx changeset version locally to update versions and the changelog
  4. Commit and push these changes to the main branch
  5. Create a GitHub release manually with the new version number

Best Practices for Contributors#

Contributors should follow these best practices to ensure smooth release management:

  1. Create changesets for all significant changes
  2. Use appropriate version types (patch, minor, or major) based on the impact of the change
  3. Provide clear, concise descriptions in changeset files
  4. Allow the automated workflows to handle version bumping and changelog updates
  5. Review the generated changelog before finalizing a release

Troubleshooting#

Common issues with the release process include:

  1. Missing changesets: If changes don't appear in the changelog, ensure changesets were created and merged
  2. Failed workflows: Check GitHub Actions logs for error details
  3. Version conflicts: Manually resolve merge conflicts in package.json or CHANGELOG.md if they occur

Sources:

Conclusion#

The release management system for AVA SDK JS uses modern tooling to automate versioning, changelog generation, and release creation. This ensures consistent releases with comprehensive documentation of changes, which helps both the development team and downstream consumers of the SDK.