Versioning Policy

To make it easier for you to ensure multiple Pando libraries are compatible, we use the same version number for all of our packages.

Tip

The versions of the Pando packages referenced in your package.json should always match each other. If they are different it could lead to unexpected behavior.

Version strategy

Stability is essential for the ecosystem around Pando to thrive. It ensures that reusable components, libraries, tutorials, tools, and learned practices don’t unexpectedly become outdated.

This page contains the practices we follow to provide a leading-edge library with a focus on stability to ensure changes are always introduced in a predictable way.

Pando follows . Pando version numbers have three parts: [major].[minor].[patch] (e.g. 5.1.3) These numbers increase based on the level of change introduced in a release.

contain new features. Some developer assistance may be expected during the update although we strive to stay backwards compatible. When upgrading to a new major release, you may need to run update scripts, refactor code, run additional tests, and learn new APIs.

contain important new features. Minor releases are fully backwards-compatible so code modifications are not expected to be required during an update, but you have the option to modify your apps and libraries to begin using new APIs, features, and capabilities introduced in the release.

are reserved only for the most critical bugs and security vulnerabilities. No code changes should be expected during an update.

Release frequency

A regular schedule of releases helps you plan and coordinate your updates with the continuing evolution of Pando.

In general, you can expect the following release cycle:

• A major release every 12 months.

• 1-3 minor releases for each major release.

• A patch release anytime for urgent bugfixes.

You can follow our for a detailed review of what releases contain.

The development, releases, and timing of any features or functionality remains at the sole discretion of Pluralsight Design. The roadmap does not represent a commitment, obligation, or promise to deliver at any time.

Major releases

Breaking changes are inconvenient for everyone, so we try to keep the number of major releases to a maximum of one per year and ideally even less often.

Instead, we release new features in minor versions. This allows you to update your apps and libraries at your own pace and to take advantage of new features as they become available.

Commitment to stability

As we change Pando over time, we try to minimize the effort required to take advantage of new features. When possible, we’ll continue to keep an older API working. In some cases that may mean putting it in a separate package.

To make it as easy as possible to upgrade to new versions of our packages we will not introduce large changes without a migration path - we do not want users to be stuck on old versions. In many cases we will write automated scripts to upgrade component syntax, which we will then include in the open-source release for anyone who would like to use them.

Gradual upgrades via warnings

Development builds of our packages include many helpful warnings. Whenever possible, we add warnings in preparation for future breaking changes. If your app has no warnings on the latest release it should be compatible with the next major release. This allows you to upgrade your apps one component (or whichever you use) at a time.

Development warnings should never affect the runtime behavior of your app. Your app should behave the same way between the development and production builds — the only differences are that the production build won’t log the warnings and that it is more efficient. (If you ever notice otherwise, please file an issue.)

What Counts as a Breaking Change?

In general, we don’t bump the major version number for changes to:

• Development warnings. Since these don’t affect production behavior, we may add new warnings or modify existing warnings in between major versions. In fact, this is what allows us to reliably warn about upcoming breaking changes.

• APIs starting with unstable. These are provided as experimental features whose APIs we are not yet confident in. By releasing these with an unstable_ prefix, we can iterate faster and get to a stable API sooner.

• Alpha and canary versions of our packages. We provide alpha/next versions of our packages as a way to test new features early, but we need the flexibility to make changes based on what we learn in the alpha period. If you use these versions, note that APIs may change before the stable release.

• Undocumented APIs and internal data structures. If you access internal property names like SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED or psInternalInstance$uk43rzhitjg, there is no warranty. You are on your own.

This policy is designed to be pragmatic: certainly, we don’t want to cause headaches for you. If we bumped the major version for all of these changes, we would end up releasing more major versions and ultimately causing more versioning pain for the community. It would also mean that we couldn’t make progress in improving our packages as fast as we’d like.

That said, if we expect that a change on this list will cause broad problems in the community, we will still do our best to provide a gradual migration path.

Patch releases and minor releases

It’s possible that a minor release will not include new features. This is allowed by semver, which states “[a minor version] MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes.”

However, it does raise the question of why these releases aren’t versioned as patches instead.

The answer is that any change to our packages (or any software) carries some risk of breaking in unexpected ways. For example, if a patch release were released to fix one bug, but accidentally introduced a different one. This would not only be disruptive to developers but also harm their confidence in future patch releases.

While we have a pretty good track record for keeping our package releases free of bugs, patch releases have an especially high bar for reliability because most developers assume they can be adopted without adverse consequences.

Because of this, we reserve patch releases only for the most critical bugs and security vulnerabilities.

If a release includes non-essential changes — such as internal refactors, changes to implementation details, performance improvements, or minor bugfixes — we will bump the minor version even when there are no new features.