Dependency Pinning Guide

This guide will show you how to pin a specific version of a dependency in your application. This guide will focus on the EasyPost client libraries, but these rules can be applied to most dependencies.

Pinning a specific version (or a specific range of versions) of a library or dependency in your project will help mitigate incompatibilities and prevent accidental upgrades and breaking changes.

EasyPost utilizes semantic versioning(opens in a new tab) for its client libraries, where versions follow an X.Y.Z naming pattern. Changes to the X number indicate major changes to architecture or breaking changes in behavior. Changes to the Y number indicate minor changes that will be backwards compatible with older versions, typically in the form of new features. Changes to the Z number indicate patch changes, which are often bug fixes or security patches that do not introduce incompatibility issues.

You may want to avoid upgrading to the next major version of a dependency, as it may require refactoring of your application to accommodate breaking changes. Minor versions and patch versions are generally considered safe to upgrade to automatically, as they should not require any refactoring, and can introduce important fixes.

To prevent your application from automatically installing and using the latest release of a dependency, you should pin a dependency to a specific version. For example, you can pin a dependency to version 2.1.0, guaranteeing that your application will only ever use version 2.1.0 of that dependency.

Alternatively, you can pin a dependency to a specific version range. For example, you can pin a dependency to version 2.*. This will mean your application will always use the latest release of major version 2 of the dependency. This will allow you to automatically adopt the minor and patch updates to the dependency, but remain on major version 2.

Let's look at some scenarios of how version pinning would work. Let's assume you are currently using version 2.1.0 of a dependency.

Since minor and patch releases are often considered safe to upgrade to, bringing necessary updates without any breaking changes, you might consider using a 2.1.* or 2.* pinning pattern in this scenario.

To prevent your application from automatically installing and using the latest release of a dependency, you should pin a dependency to a specific version. For example, you can pin a dependency to version 2.1.0, guaranteeing that your application will only ever use version 2.1.0 of that dependency.

Most package managers (e.g. PIP for Python, NuGet for C#, NPM for Node.js) respect semantic versioning and dependency pinning, meaning your requested pinning rules will be honored when you update your dependencies.

Below are instructions for pinning dependencies for each programming language EasyPost officially supports.

In your list of dependencies (typically a requirements.txt or setup.py file), you can pin dependencies using Version Specifiers(opens in a new tab). The following will show you how to pin specific versions of the EasyPost client library.

In your list of dependencies (typically a composer.json file), you can pin dependencies using Version Constraints(opens in a new tab). The following will show you how to pin specific versions of the EasyPost client library.

In your list of dependencies (typically a package.json file), you can pin dependencies using Version Ranges(opens in a new tab). The following will show you how to pin specific versions of the EasyPost client library.

In your list of dependencies (typically a .gemspec file), you can pin dependencies using Version Constraints(opens in a new tab). The following will show you how to pin specific versions of the EasyPost client library.

In your list of dependencies (typically a pom.xml file for Maven, or a build.gradle file for Gradle), you can pin dependencies using Version Ranges(opens in a new tab). The following will show you how to pin specific versions of the EasyPost client library.

In your list of dependencies (typically a .csproj file for C# projects, a .fsproj for F# projects, or a .vbproj file for Visual Basic projects), you can pin dependencies using Version Ranges(opens in a new tab). The following will show you how to pin specific versions of the EasyPost client library.

In your list of dependencies (typically a go.mod file), you can pin dependencies using Version Queries(opens in a new tab). (NOTE: After v2 of a Go dependency is released, you must define a major version suffix(opens in a new tab)). The following will show you how to pin specific versions of the EasyPost client library.