Contributing to Releases

We use changesets to manage version bumps and release notes for our monorepo’s artifacts (NPM packages, Docker images, and Lambda zips).

Adding a Changeset to Your PR

When you open a PR with feature or bug fix changes, you’ll need to include a changeset file that documents your changes:

1. Run changeset or pnpm changeset in the repository root.
2. Select the packages/apps your changes affect using the interactive prompt.
3. Choose whether your changes are “major” (breaking changes), “minor” (features), or “patch” (bug fixes).
4. Write a clear description of your changes - this will appear in the release notes.

The changesets/bot will automatically comment on your PR to either remind you to add a changeset or confirm the version changes that will happen when your PR is merged.

Important notes:

• Changesets are only required for user-facing changes (features, bug fixes).
• You don’t need a changeset for documentation changes or internal refactoring.
• All our apps and packages (with an exception as noted below) use “fixed” versioning - they all share the same version number regardless of which app or package triggered the version bump.
• An exception to the above “fixed” versioning is the “fallback-ensapi” app. This is a Lambda containing logic specific to NameHash deployments of ENSNode and is versioned independently.

Creating a Release

Upon the publishing of a new release, your change will be included in the produced artifacts and your contributions will be referenced in the GitHub Release notes. There are three different types of releases that your changes can be included in for produced artifacts.

Full Release

Workflow File: release.yml

If your PR includes a changeset and is merged to main then it will automatically be added to a new automated Release PR by the Changesets bot. As more changesets are added to main the Release PR will continue to update. Once a Release PR is merged into main it triggers a “full” release that will:

• Build and publish all of the monorepo’s artifacts (NPM packages, Docker images, and Lambda zips).
• Create a release on GitHub with autogenerated release notes from all the included changesets.

Important notes:

• Among all release types, only Full Releases are considered stable.
• Full releases are triggered through merging the Release PR to main.
• All ENSNode packages use “fixed” versioning. Once a full release is published they will all advance to the version indicated in the Release PR based on the included changesets.
• Only members of the NameHash Labs ensnode team have the required permissions to merge the Release PR to main.
• Full releases will create GitHub tags and release notes.

Snapshot Release

Workflow File: release_snapshot.yml

Each commit to main will automatically trigger the release_snapshot.yml workflow to build and publish all of the monorepo’s artifacts. These public releases will be under the tag @next, allowing anyone to use the artifacts associated with each commit to main. To install snapshot releases run pnpm install @ensnode/[package-name]@next or docker run ghcr.io/namehash/ensnode/[app-name]:next.

Important notes:

• Snapshot releases are part of the pre-stable state of the main branch and should be installed with caution until a full release is published.
• Release snapshots are automatic and cannot be triggered manually.
• Snapshot releases will include the @next tag for published artifacts.
• Published artifacts will advance to the version that was included in the changeset of the PR merged to main.
• The main branch of ensnode is protected. Only PRs approved by the ensnode team can be merged to main and trigger a snapshot release.
• No GitHub releases or tags are created for snapshot releases.

Preview Release

Workflow File: release_preview.yml

To test or install a package before merging it into main, a preview release can be used. Each preview release is associated with a PR, and the PR will receive a comment with installation instructions. To manually trigger a preview release, follow these steps:

1. Navigate to Actions > Release Preview
2. Click “Run workflow” and select from the following options:

• The branch on which to run the preview release workflow. The branch must have an open PR.
• Choose which artifacts to build and publish:
  • npm-only: NPM packages only
  • npm-and-lambdas: NPM packages + Lambda functions
  • npm-and-ghcr: NPM packages + Docker images
  • all: NPM packages + Lambda functions + Docker images
• (Optional) Provide a custom suffix for the preview release tag. For example, if you had a branch called feat/add-api-route and left this custom suffix field blank, the preview release would be @ensnode/[package-name]@preview-feat-add-api-route. If you fill in the custom suffix field with users-route then the resulting tag name would be @ensnode/[package-name]@preview-users-route.

3. The workflow will post a comment on the PR with installation instructions. If multiple preview releases are triggered for the same PR, the comment will update with the latest release info.
4. Install preview packages with: npm install @ensnode/[package-name]@preview-branch-name.

Important notes:

• Preview releases require an open PR. The workflow will abort if no PR exists for the branch.
• Preview releases are not guaranteed to be stable as they are still under active development.
• Preview releases can only be triggered manually by authorized NameHash team members.
• Preview releases will include the @preview-* tag for published artifacts, followed by either the name of the branch or the custom suffix chosen during the action trigger.
• Published artifacts will advance to the version that was included in the changeset of the selected branch.
• No GitHub releases or tags are created for preview releases.

Selecting a Release for Deployment or Installation

Caution

ENSNode is currently not using Semantic Versioning. Patches and minor releases may include breaking changes.

When using ENSNode artifacts, you have several release types to choose from.

Where to Find Releases

• NPM Packages: Available on the npm registry under the @ensnode organization.
• Docker Images: Available on GitHub Container Registry.
• GitHub Releases: Full releases are documented with release notes on the ENSNode GitHub releases page.
• Lambda Zip Artifacts: Available in the Artifact section of a successful workflow run. These Action Artifacts are retained for 90 days.

Choosing the Right Release Type

Pinned Full Release Versions

Note

In the installation examples below, [version] is a placeholder that must be replaced with a specific version number from the Releases Page. Pinning to specific versions is critical for all published assets because the latest tag is a mutable pointer. Each time you pull or redeploy, you may receive a different version, introducing unexpected breaking changes or bugs into your running deployment without warning.

npm install @ensnode/[package-name]@[version]
docker run ghcr.io/namehash/ensnode/[app-name]:[version]

Pinned full releases are required for those who want to use any published ENSNode artifacts. By using a pinned version you can maintain full control over features or patches that might be included. This is specifically important for ENSNode as a new version might require updates to environment variables such as DATABASE_SCHEMA or change how ENSNode apps work together. Review the release notes on the Releases Page to help decide which version to install.

Snapshot Releases

Caution

The next tag is a floating pointer that always references the most recent snapshot release. When using Docker images with the next tag, you must run docker pull to update your local Docker cache if you want to get the actual latest image. Without pulling, you may continue using an older cached version.

npm install @ensnode/[package-name]@next
docker run ghcr.io/namehash/ensnode/[app-name]:next

Snapshot releases should be used by those who need to test features or patches before they are included in full releases. These releases follow the main branch and are not referenced in the GitHub Releases page. Instead they are installed by using the next tag for published artifacts.

Caution

Snapshot releases may contain unstable changes and should only be used in development environments.

Preview Releases

Note

The example below is a mock of what a preview release might look like. Read the preview releases section for more information.

npm install @ensnode/[package-name]@[preview-branch-name]
docker run ghcr.io/namehash/ensnode/[app-name]:[preview-branch-name]

Preview releases are designed to test features or patches on a PR branch before it is merged to main. Each preview release is associated with a PR, and the PR will have a comment with installation instructions. Since preview releases can contain experimental and unstable changes, they should be avoided unless you are actively contributing through a PR and need to test work on a branch.

Caution

Avoid using preview releases unless you are actively contributing to ENSNode and need to test changes on an active PR.