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.

• Why to Pin a Dependency
• How Dependency Pinning Works
• How to Pin Dependencies Using Package Managers
  • Python
  • PHP
  • Node.js
  • Ruby
  • Java
  • C#
  • Golang

Why to Pin a Dependencylink

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 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.

How Dependency Pinning Workslink

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.

How to Pin Dependencies Using Package Managerslink

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.