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

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 Works

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.

I have pinned:If 2.1.1 comes out:If 2.2.0 comes out:If 3.0.0 comes out:
2.1.0Keep using 2.1.0Keep using 2.1.0Keep using 2.1.0
2.1.*Upgrade to 2.1.1Keep using 2.1.0Keep using 2.1.0
2.*Upgrade to 2.1.1Upgrade to 2.2.0Keep using 2.1.0
*Upgrade to 2.1.1Upgrade to 2.2.0Upgrade to 3.0.0

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 Managers

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.

Python

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

I want:Dependency pin rule:Will automatically update to:
Version 2.1.0, alwayseasypost==2.1.02.1.0
The latest patch updates in version 2.1easypost==2.1.*2.1.0, 2.1.1
The latest minor updates in version 2easypost==2.*2.1.0, 2.1.1, 2.2.0, 2.2.1
The latest version, alwayseasypost2.1.0, 2.1.1, 2.2.0, 2.2.1, 3.0.0, 3.0.1

PHP

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

I want:Dependency pin rule:Will automatically update to:
Version 2.1.0, always"easypost/easypost-php": "~2.1.0"2.1.0
The latest patch updates in version 2.1"easypost/easypost-php": "~2.1"2.1.0, 2.1.1
The latest minor updates in version 2"easypost/easypost-php": "~2"2.1.0, 2.1.1, 2.2.0, 2.2.1
The latest version, always"easypost/easypost-php": ">=2.1.0" // v2.1.0 as a minimum2.1.0, 2.1.1, 2.2.0, 2.2.1, 3.0.0, 3.0.1

Node.js

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

I want:Dependency pin rule:Will automatically update to:
Version 2.1.0, always"@easypost/api": "~2.1.0"2.1.0
The latest patch updates in version 2.1"@easypost/api": "~2.1"2.1.0, 2.1.1
The latest minor updates in version 2"@easypost/api": "~2"2.1.0, 2.1.1, 2.2.0, 2.2.1
The latest version, always"@easypost/api": ">=2.1.0" // v2.1.0 as a minimum2.1.0, 2.1.1, 2.2.0, 2.2.1, 3.0.0, 3.0.1

Ruby

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

I want:Dependency pin rule:Will automatically update to:
Version 2.1.0, alwaysgem 'easypost', '~> 2.1.0', '< 2.1.1'2.1.0
The latest patch updates in version 2.1gem 'easypost', '~> 2.1'2.1.0, 2.1.1
The latest minor updates in version 2gem 'easypost', '~> 2'2.1.0, 2.1.1, 2.2.0, 2.2.1
The latest version, alwaysgem 'easypost', '>= 2.1.0' // v2.1.0 as a minimum 2.1.0, 2.1.1, 2.2.0, 2.2.1, 3.0.0, 3.0.1

Java

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. The following will show you how to pin specific versions of the EasyPost client library.

I want:Dependency pin rule:Will automatically update to:
Version 2.1.0, alwaysMaven:
<dependency>
<groupId>com.easypost</groupId>
<artifactId>easypost-api-client</artifactId>
<version>[2.1.0]</version>
</dependency>

Gradle:
implementation 'com.easypost:easypost-api-client:[2.1.0]'
2.1.0
The latest patch updates in version 2.1Maven:
<dependency>
<groupId>com.easypost</groupId>
<artifactId>easypost-api-client</artifactId>
<version>[2.1.0,2.2.0)</version>
</dependency>

Gradle:
implementation 'com.easypost:easypost-api-client:[2.1.0,2.2.0)'
2.1.0, 2.1.1
The latest minor updates in version 2Maven:
<dependency>
<groupId>com.easypost</groupId>
<artifactId>easypost-api-client</artifactId>
<version>[2.1,3.0.0)</version>
</dependency>

Gradle:
implementation 'com.easypost:easypost-api-client:[2.1,3.0.0)'
2.1.0, 2.1.1, 2.2.0, 2.2.1
The latest version, alwaysMaven:
<dependency>
<groupId>com.easypost</groupId>
<artifactId>easypost-api-client</artifactId>
<version>[2.1.0,)</version> // v2.1.0 as a minimum
</dependency>

Gradle:
implementation 'com.easypost:easypost-api-client:[2.1.0,)'
2.1.0, 2.1.1, 2.2.0, 2.2.1, 3.0.0, 3.0.1

C#

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

I want:Dependency pin rule:Will automatically update to:
Version 2.1.0, always<PackageReference Include="EasyPost-Official" Version="[2.1.0]" />2.1.0
The latest patch updates in version 2.1<PackageReference Include="EasyPost-Official" Version="[2.1.0, 2.2.0)" />2.1.0, 2.1.1
The latest minor updates in version 2<PackageReference Include="EasyPost-Official" Version="[2.1.0, 3.0.0)" />2.1.0, 2.1.1, 2.2.0, 2.2.1
The latest version, always<PackageReference Include="EasyPost-Official" Version="2.1.0" /> // v2.1.0 as a minimum 2.1.0, 2.1.1, 2.2.0, 2.2.1, 3.0.0, 3.0.1

Golang

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

I want:Dependency pin rule:Will automatically update to:
Version 2.1.0, alwaysgithub.com/EasyPost/easypost-go/v2 v2.1.02.1.0
The latest patch updates in version 2.1github.com/EasyPost/easypost-go/v2 <v2.2.02.1.0, 2.1.1
The latest minor updates in version 2github.com/EasyPost/easypost-go/v2 <3.0.0
or
github.com/EasyPost/easypost-go/v2 latest
2.1.0, 2.1.1, 2.2.0, 2.2.1
The latest version, alwaysNot possible.
You have to limit a dependency to a major version for automatic updates (see above).
You will need to manually change the major version suffix to upgrade to the next major version.
N/A