The DevXP engineering team hosts office hours every Thursday at 11 a.m. Pacific Time where we answer your questions live and help you get up and running with Flatfile. Join us!
The versioning of our npm packages adheres to Semantic Versioning (SemVer) principles, providing an unambiguous reflection of changes in each new release. Each version number is denoted in the format of: MAJOR.MINOR.PATCH Given this structure:
  • The MAJOR version increment denotes incompatible API changes.
  • The MINOR version increment denotes backward-compatible functionality additions.
  • The PATCH version increment denotes backward-compatible bug fixes.

​
Packages in Development

In certain cases, namely during the development stage, a package version might start with 0.x.x. This indicates that there’s no guarantee of API stability or backward compatibility. For packages in this stage, the rules for version increments are slightly different:
  • Minor version 0.y.z is incremented for each subsequent release.
  • Patch version 0.0.z is incremented for backward-compatible bug fixes.

​
Transitioning to Stability

When a package reaches stability, we start the version at 1.0.0. This is because the caret (^) in the ^1.x.x pattern allows minor and patch updates that are supposed to be backward-compatible. Conversely, if ^1.0.x is used, only patch updates are allowed. This adheres to SemVer conventions, indicates API stability, sets clear expectations, and allows for safer automatic updates.

​
Principles of Semantic Versioning

Following the Semantic Versioning (SemVer) principles allows us to communicate effectively about the changes in our software, particularly in terms of compatibility and stability. Here are the core principles we follow:

​
MAJOR Version

The MAJOR version increment represents incompatible changes in our software. This signals users and system administrators that significant modifications may be required to accommodate the new version.

​
MINOR Version

The MINOR version increment represents the addition of backward-compatible functionalities. These new features should not interfere with the existing system setup, and users can continue using the software without any significant adjustments.

​
PATCH Version

The PATCH version increment signifies backward-compatible bug fixes. This ensures users have access to the most stable and reliable version of the software without changes in functionality or system compatibility.

​
Summary

By adhering to these Semantic Versioning (SemVer) principles, we strive to maintain and communicate the balance between introducing new functionalities, fixing bugs, and ensuring backward compatibility. Our aim is to provide clarity and confidence to our users and stakeholders about the changes they can expect in each new software version.