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 packages use “fixed” versioning - they all share the same version number regardless of which package triggered the version bump.

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 the Release PR is merged into main then it will trigger a stable release with all of the included changesets. It will also create a release on GitHub with autogenerated release notes. When a full release runs it will build and publish all of the monorepo’s artifacts (NPM packages, Docker images, and Lambda zips).

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. To manually trigger a preview release for a branch, 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. Any branch other than main can be selected. Using a branch with an active PR allows the workflow to add a GitHub comment containing the installation information. If multiple preview releases are triggered for the same brach/PR, the GitHub comment will update with the latest release.
• Choose which artifacts to build and publish (NPM packages, Docker images, Lambda zips, or any combination).
• (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. Install preview packages with: npm install @ensnode/[package-name]@preview-branch-name.

Important notes:

• Preview releases are generally built and published from branches with active PRs. They are not guaranteed to be stable as they are still under active development.
• Preview releases can only be triggered manually.
• 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.
• Preview releases can only be triggered by authorized NameHash team members.
• No GitHub releases or tags are created for Preview Releases.

Selecting a Release for Deployment or Installation

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

Choosing the Right Release Type

Pinned Full Release Versions

Note

The example version below of 1.0.0 is a placeholder. Visit the Releases Page to pick a pinned full release.

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

Pinned full releases are recommended for those who want to start using ENSNode artifacts. By using a pinned version you can maintain full control over features or patches that might be included. Review the release notes on the Releases Page to help decide which version to install.

Caution

Never use the latest tag for Docker deployments (e.g., ghcr.io/namehash/ensnode:latest or ghcr.io/namehash/ensnode). The latest tag is a mutable pointer that will automatically pull different versions over time, causing unexpected updates and potential breaking changes in your deployment. Always pin to a specific version number from the GitHub releases page.

Snapshot Releases

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 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 branch that have not been merged to the main branch, which means they can contain experimental and unstable changes. Therefore preview releases 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 branch.