How Insomnia Ships Software

Overview

In general, Insomnia follows semantic versioning. (aka major.minor.patch)

All changes to Insomnia are communicated via our changelog, and via our GitHub releases page. All versions of Insomnia are supported by public documentation updates.

When to update

You are free to update as often as you like, or to continue using past versions. In general, you should think of Insomnia versions like browser versions - unless you have a specific reason, probably best to stay on the newest version.

Insomnia strongly recommends that all users collaborating on the same project strive to remain on the same major version as often as possible. 

Long Term Support (LTS)

We do not have an explicit Long Term Support (LTS) policy, nor do we publish LTS versions. We will consider this in the future.  

We will investigate and debug support issues or bugs filed based on any version from the last 12 months. In some cases it may be necessary to upgrade to complete the investigation. 

For versions more than 12 months out of date, we will provide as much assistance as we reasonably can, but cannot guarantee any particular outcome or level of assistance. We strongly recommend upgrading to see if your issue is resolved in a newer version.

Patching Backwards

For 12.6.0 and earlier versions, we do not backport fixes or changes. Best practice is to upgrade to as new a version as possible.

For 13.0.0 and on, we will consider backporting across major versions when absolutely necessary. For example, if we release a patch in 14.6.3, we’d consider releasing a new patch for 13 as well, but a user on 14.5.1 would need to upgrade to 14.6.3. Though we aim to be as helpful as possible, Insomnia reserves complete control over whether to fix bugs in prior versions at our sole discretion. 

Insomnia will not roll new or modified functionality into prior versions except in extraordinary circumstances, at our sole discretion.

Types of Versions

Major Versions (aka v12)

  • Shipped about twice a year (not necessarily every six months).
  • Will be released in beta for 7 days before GA.
  • May contain changes or fixes that are not backwards compatible.  See breaking changes below.  These changes could in theory impact how any user works.
  • We recommend a greater level of care or attention to detail when switching major versions.
  • Contains new features, bugs, architecture improvements, etc.

Minor Versions (aka v12.1)

  • Shipped approximately every four weeks.
  • Will be released in beta for 7 days before GA.
  • Will always be compatible across its parent major version.
  • Minor automated or manual migrations may be necessary. Insomnia will automate as much as possible and guide the user where else needed.
  • Contains new features, bugs, architecture improvements, etc.

Patch Versions (aka v12.1.1)

  • Shipped when needed within a minor version.
  • May or may not involve a beta, of any length, depending on the issue.
  • Never contains any enhancements or new functionality. Only contains defect fixes, security patches or other maintenance work.

Breaking Changes

Insomnia reserves the right to change and improve its software and feature set however we deem necessary. As such, it will occasionally be necessary to introduce changes that are not backwards compatible or to significantly change how our users interact with our software.

We will always strive to minimize user disruption via quality assurance, clear user expectations, automated or manual user migrations, and guiding users at each step.

In the rare event that we need to remove or reduce any core functionality or interface, we will take all reasonable steps to communicate this in advance via our blog and marketing channels. As often as possible, we will automatically handle and resolve any breaking changes and no manual user intervention will be required either from end users or account administrators. In the rare event that manual user intervention is required, we guarantee 30 days notice via the channels above. Enterprise customers will also receive guidance from their customer success managers. 


For lesser changes - such as renaming a button or replacing two tabs with one - we will communicate these changes clearly in our changelog, public documentation and via our marketing channels as part of the GA release.


Rarely, a third party dependency or library might implicitly change Insomnia’s functionality, particularly in a minor way. In those cases, we will make all commercially reasonable efforts to identify this in advance, either mitigating it or communicating it clearly as above.

Changes in Major Versions

We increment the major version when the release contains breaking changes i.e. anything that could cause an existing workflow, configuration, or integration to stop working after upgrade.

Examples:

  • Removing a supported request type, protocol, or authentication method
  • Removing or renaming a CLI command, flag, or subcommand
  • Changing the structure or schema of exported Insomnia collections/environments in a backwards-incompatible way
  • Dropping support for an operating system, platform, or runtime version
  • Changing the plugin API in a way that breaks existing plugins
  • Removing or renaming a public API endpoint (Insomnia Cloud / sync)
  • Changing the default behavior of an existing feature in a way that alters outcomes for any non-trivial number of current users (e.g. changing how variables resolve, changing request execution order)
  • Migrating the underlying data store or storage format in a way that prevents rollback to a prior version
  • Removing a UI panel, tab, or workflow that a non-trivial number of users depend on.

Changes in Minor versions

We Increment the minor version when the release adds new functionality that is fully backwards-compatible with the previous version.

Examples:

  • Adding a new request type, protocol, or authentication method
  • Adding a new CLI command, flag, or subcommand
  • Introducing a new UI panel, tab, or workflow
  • Adding new fields or options to the collection/environment export format (existing fields unchanged)
  • Adding a new plugin hook or extending the plugin API without breaking existing plugins
  • Adding support for a new operating system or platform
  • Deprecating (but not yet removing) a feature, command, or API
  • Adding new environment variable types or template tag functions
  • Introducing a new integration (e.g. a new Git provider, a new CI/CD integration)
  • Adding new configuration options or preferences

Changes in Patch versions

We increment the patch version when the release contains only backwards-compatible bug fixes i.e. corrections that make Insomnia behave the way it was already documented or intended to behave.

Examples:

  • Fixing a crash or hang during request execution
  • Correcting response rendering or syntax highlighting errors
  • Fixing import/export issues where valid collections failed to load
  • Resolving authentication flows that were not completing correctly
  • Fixing environment variable resolution or template tag evaluation bugs
  • Correcting UI rendering glitches or layout issues
  • Fixing sync/collaboration conflicts or data loss scenarios
  • Updating bundled dependencies to patch security vulnerabilities (with no user-facing behavior change)
  • Fixing incorrect HTTP header handling or encoding issues
  • Correcting documentation links or in-app help text

Types of Releases

  • Generally Available (GA) - Available to anyone.
  • Beta - Generally a 7 day period before GA where clients can opt in (via the Settings -> Release Channel in the app) and provide us early feedback. (See feedback elsewhere in this doc). Note we are conducting our own final testing/reviews at the same time - this is safe for general use, but not guaranteed to be as stable as GA.
  • Preview / Tech Preview - Features that are ready for usage by any customer, but are still in active development because it is a new problem space or we are still iterating on what is possible. This feature will always be clearly marked as such in our product.
  • This is similar, but not identical to, Kong’s Tech Preview.

Feedback

Your feedback always makes us better, and is especially critical for features that are in beta or preview.

  • Essentials customers can file GitHub issues for defects or ideas.
  • Pro and Enterprise customers can reach out to support@insomnia.rest for support.
  • Enterprise customers can communicate their feedback to their CSM or through whatever normal cadences they have with Kong/Insomnia.

Disclaimer

Insomnia recognizes the risk and pain that significant or breaking changes offer to our customers, and strives to minimize that at all times via the above guidelines. However, at all times Insomnia reserves the right to act and ship however and whenever we deem necessary in the interests of the security and stability of our products and customers.