# 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](https://semver.org/) 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.

Related:

- [EasyPost API Documentation](https://docs.easypost.com/libraries)

---

## 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.0 | Keep using 2.1.0 | Keep using 2.1.0 | Keep using 2.1.0 |
| 2.1.* | Upgrade to 2.1.1 | Keep using 2.1.0 | Keep using 2.1.0 |
| 2.* | Upgrade to 2.1.1 | Upgrade to 2.2.0 | Keep using 2.1.0 |
| * | Upgrade to 2.1.1 | Upgrade to 2.2.0 | Upgrade 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](https://peps.python.org/pep-0440/#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, always | easypost==2.1.0 | 2.1.0 |
| The latest patch updates in version 2.1 | easypost==2.1.* | 2.1.0, 2.1.1 |
| The latest minor updates in version 2 | easypost==2.* | 2.1.0, 2.1.1, 2.2.0, 2.2.1 |
| The latest version, always | easypost | 2.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](https://getcomposer.org/doc/articles/versions.md#writing-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 minimum | 2.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](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#dependencies). 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 minimum | 2.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](https://guides.rubygems.org/patterns/). The following will show you how to pin specific versions of the EasyPost client library.

[Content omitted: table content. Review the rendered documentation for complete tabular data.]

### 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](https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html). The following will show you how to pin specific versions of the EasyPost client library.

[Content omitted: table content. Review the rendered documentation for complete tabular data.]

### C#/.NET

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](https://learn.microsoft.com/en-us/nuget/concepts/package-versioning#version-ranges). The following will show you how to pin specific versions of the EasyPost client library.

[Content omitted: table content. Review the rendered documentation for complete tabular data.]

### Golang

In your list of dependencies (typically a **go.mod** file), you can pin dependencies using [Version Queries](https://go.dev/ref/mod#version-queries). (NOTE: After v2 of a Go dependency is released, you must define a [major version suffix](https://go.dev/ref/mod#versions:~:text=com/mod%40abcd1234-,Major%20version%20suffixes,-Starting%20with%20major)). 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 | github.com/EasyPost/easypost-go/v2 v2.1.0 | 2.1.0 |
| The latest patch updates in version 2.1 | github.com/EasyPost/easypost-go/v2 <v2.2.0 | 2.1.0, 2.1.1 |
| The latest minor updates in version 2 | github.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, always | Not 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 |