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 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 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

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.
• 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 can only be triggered manually.
• 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.
• Published packages/images 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 installing ENSNode NPM packages or Docker images, 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

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:1.0.0

Pinned full releases are recommended for those who want to start using ENSNode packages or Docker images. By using a pinned version you can maintain full control over features or patches that might be included. Feview 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: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 NPM packages or Docker images.

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: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.