Contributing to Releases

We use changesets to manage version bumps and release notes for our NPM packages and Docker images (ENSIndexer, ENSAdmin, and ENSRainbow).

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 packages/images 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 packages/images.

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 packages to NPM and Docker images to GitHub Container Registry (ghcr).

Important Notes:

• Among all release types, only Full Releases are considered stable.
• Full releases will include the @latest tag for published packages/images.
• 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 packages to NPM and Docker images to the GitHub Container Registry (ghcr). These public releases will be under the tag @next, allowing anyone to use the npm packages or docker images associated with each commit to main. To install snapshot releases run pnpm install @ensnode/package-name@next or docker run ghcr.io/namehash/ensnode: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 packages/images.
• Published packages/images 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

In the event that a package needs to be tested or installed before it is merged 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:

• Which branch you would like to run the preview release workflow on. You can choose any branch other than main and it will trigger a preview release for it, however it is recommended to use the branch where there is an active PR so the workflow can add a GitHub comment to the PR. The GitHub comment will contain helpful installation info such as the generated release tag, which would otherwise have to be located manually through the action logs or the publishing registries.
• Choose whether to build and publish only NPM packages, or to build and publish both NPM packages and Docker images to the GitHub Container Registry (ghcr).
• (Optional) Provide a custom suffix for the preview release package 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 will include the @preview-* tag for published packages/images, followed by either the name of the branch or the custom suffix chosen during the action trigger.
• Preview releases can only be triggered by authorized NameHash team members.
• Preview releases are ephemeral and don’t create commits or modify the repository.
• No GitHub releases or tags are created for Preview Releases.

Selecting a Release for Deployment or Installation

When installing ENSNode NPM packages or Docker images, you have several release types to choose from depending on your needs and risk tolerance.

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

Choosing the Right Release Type

For Production Use: @latest (Full Releases)

npm install @ensnode/package-name@latest
docker run ghcr.io/namehash/ensnode:latest

When to use:

• When you need maximum stability and reliability
• When you want thoroughly tested features

What to expect:

• Stable, well-tested releases
• Complete release notes and changelog entries

For Development/Testing: @next (Snapshot Releases)

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

When to use:

• Development environments
• When you want to test upcoming features before they’re stable

What to expect:

• Latest features and bug fixes from the main branch
• May contain breaking changes or unstable features
• More frequent updates (every commit to main)

For Feature Testing: @preview-* (Preview Releases)

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

When to use:

• Testing specific features before they’re merged
• Collaborating on development work
• Validating fixes for specific issues

What to expect:

• Experimental and potentially unstable
• Built from active development branches
• May not be compatible with other packages

Version Selection Best Practices

• Check the GitHub releases page for the latest stable version and release notes
• Pin specific versions in your integrations rather than using tags like @latest
• Use full releases (@latest) as much as possible for stability
• Only use snapshot releases (@next) for experimenting with new features
• Avoid using preview releases (@preview) unless you are actively contributing through a PR