# Creating a Release There are three different types of ENSNode releases: Full Release, Snapshot Release, and Preview Release. ## Full Release Workflow File: [release.yml](https://github.com/namehash/ensnode/blob/main/.github/workflows/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](https://github.com/namehash/ensnode/blob/main/.github/workflows/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](#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](https://github.com/namehash/ensnode/blob/main/.github/workflows/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](https://github.com/namehash/ensnode/actions/workflows/release_preview.yml) 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](https://semver.org/). 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](https://www.npmjs.com/search?q=%40ensnode) under the `@ensnode` organization. - **Docker Images**: Available on [GitHub Container Registry](https://github.com/orgs/namehash/packages?repo_name=ensnode). - **GitHub Releases**: Full releases are documented with release notes on the [ENSNode GitHub releases page](https://github.com/namehash/ensnode/releases). - **Lambda Zip Artifacts**: Available in the [Artifact section](https://github.com/actions/upload-artifact?tab=readme-ov-file#where-does-the-upload-go) of a successful workflow run. These Action Artifacts are [retained for 90 days](https://github.com/actions/upload-artifact?tab=readme-ov-file#retention-period). ## Choosing the Right Release Type ### Pinned Full Release Versions When deploying ENSNode to production environments, it is advisable to use a Pinned Full Release. 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. Review the release notes on the [Releases Page](https://github.com/namehash/ensnode/releases) to help decide which version to install. ```bash npm install @ensnode/[package-name]@[version] docker run ghcr.io/namehash/ensnode/[app-name]:[version] ``` :::caution When installing NPM packages for use in production environments, it is also advisable to pin a specific Pinned Full Release version number. ENSNode patch version increments MAY include breaking changes, so the usage of exact version package specifiers is encouraged. For example: ✅ `"@ensnode/[package-name]": "1.0.0"` ❌ `"@ensnode/[package-name]": "^1.0.0"` And when installing from the command line: ✅ `pnpm install @ensnode/[package-name]@1.0.0` ❌ `pnpm install @ensnode/[package-name]` ::: :::caution In particular, when deploying ENSNode to production environments, using the `latest` Docker tag without strict pull policies could result in a version mismatch between interdependent ENSNode apps (which will helpfully crash at startup). Due to this, we highly recommend using a specific Pinned Full Release version number tag like `1.0.0` instead of the tag `latest`, which could point to different versions of the ENSNode app depending on the platform's pull policy. ::: :::caution Each ENSIndexer version update is likely to produce an updated [Ponder Build Id](https://ponder.sh/docs/api-reference/ponder/database). When updating your ENSIndexer version, you should expect to update the `ENSINDEXER_SCHEMA_NAME` environment variable to point to a new ENSDb Writer Schema in ENSDb for a complete reindexing with the new Ponder Build Id. A complete reindexing may take over 24 hours depending on your configuration. ENSNode version updates require special coordination and should not be assumed to be a simple version bump. ::: ### 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. ::: ```bash 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](#preview-release) for more information. ::: ```bash 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. :::