Skip to content

Add dependency management suggestions #819

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 6, 2025
Merged

Add dependency management suggestions #819

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions RELEASES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Microsoft Identity SDK Versioning and Servicing FAQ

We have adopted the semantic versioning flow that is industry standard for OSS projects. It gives the maximum amount of control on what risk you take with what versions. If you know how semantic versioning works with node.js, java, and ruby none of this will be new.

## Semantic Versioning and API stability promises

Microsoft Authentication libraries are independent open source libraries that are used by partners both internal and external to Microsoft. As with the rest of Microsoft, we have moved to a rapid iteration model where bugs are fixed daily and new versions are produced as required. To communicate these frequent changes to external partners and customers, we use semantic versioning for all our public Microsoft Authentication SDK libraries. This follows the practices of other open source libraries on the internet. This allows us to support our downstream partners which will lock on certain versions for stability purposes, as well as providing for the distribution over NuGet, CocoaPods, and Maven.

The semantics are: MAJOR.MINOR.PATCH (example 1.1.5)

We will update our code distributions to use the latest PATCH semantic version number in order to make sure our customers and partners get the latest bug fixes. Downstream partner needs to pull the latest PATCH version. Most partners should try lock on the latest MINOR version number in their builds and accept any updates in the PATCH number.

Example:
Using NuGet, this ensures all 1.1.0 to 1.1.x updates are included when building your code, but not 1.2.

```
<dependency
id="MSALfordotNet"
version="[1.1,1.2)"
/>
```

| Version | Description | Example |
|:-------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------:|
| x.x.x | PATCH version number. Incrementing these numbers is for bug fixes and updates but do not introduce new features. This is used for close partners who build on our platform release (ex. Azure AD Fabric, Office, etc.),In addition, Cocoapods, NuGet, and Maven use this number to deliver the latest release to customers. This will update frequently (sometimes within the same day),There is no new features, and no regressions or API surface changes. Code will continue to work unless affected by a particular code fix. | MSAL for iOS 1.0.10,(this was a fix for the Storyboard display that was fixed for a specific Office team) |
| x.x | MINOR version numbers. Incrementing these second numbers are for new feature additions that do not impact existing features or introduce regressions. They are purely additive, but may require testing to ensure nothing is impacted.,All x.x.x bug fixes will also roll up in to this number.,There is no regressions or API surface changes. Code will continue to work unless affected by a particular code fix or needs this new feature. | MSAL for iOS 1.1.0,(this added WPJ capability to MSAL, and rolled all the updates from 1.0.0 to 1.0.12) |
| x | MAJOR version numbers. This should be considered a new, supported version of Microsoft Authentication SDK and begins the Azure two year support cycle anew. Major new features are introduced and API changes can occur.,This should only be used after a large amount of testing and used only if those features are needed.,We will continue to service MAJOR version numbers with bug fixes up to the two year support cycle. | MSAL for iOS 1.0,(our first official release of MSAL) |

## Serviceability

When we release a new MINOR version, the previous MINOR version is abandoned.

When we release a new MAJOR version, we will continue to apply bug fixes to the existing features in the previous MAJOR version for up to the 2 year support cycle for Azure.
Example: We release MSALiOS 2.0 in the future which supports unified Auth for AAD and MSA. Later, we then have a fix in Conditional Access for MSALiOS. Since that feature exists both in MSALiOS 1.1 and MSALiOS 2.0, we will fix both. It will roll up in a PATCH number for each. Customers that are still locked down on MSALiOS 1.1 will receive the benefit of this fix.

## Microsoft Authentication SDKs and Azure Active Directory

Microsoft Authentication SDKs major versions will maintain backwards compatibility with Azure Active Directory web services through the support period. This means that the API surface area defined in a MAJOR version will continue to work for 2 years after release.

We will respond to bugs quickly from our partners and customers submitted through GitHub and through our private alias (tellaad@microsoft.com) for security issues and update the PATCH version number. We will also submit a change summary for each PATCH number.
Occasionally, there will be security bugs or breaking bugs from our partners that will require an immediate fix and a publish of an update to all partners and customers. When this occurs, we will do an emergency roll up to a PATCH version number and update all our distribution methods to the latest.
66 changes: 66 additions & 0 deletions dependency-management.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# Best Practices for Managing Dependency Versions

The best practices for managing dependency versions depend on
whether you are maintaining an application or a library.

## If you are maintaining an application

There are two suggestions that you shall follow.

1. Pinning dependencies in a production environment.

This refers to explicitly declaring the exact version of your application's dependencies,
including those of its dependencies (a.k.a. transitive dependencies).
This ensures consistent and predictable deployments by preventing accidental upgrades that might introduce errors or regressions.

To achieve this, the steps can be different, based on the tooling you choose.
For example, if you are using the common `pip` tool,
you shall specify the version like this `pip install PackageName==x.y.z`,
where x.y.z is the latest stable version that you have tested with your app.

Another approach is to start from a clean virtual environment,
install all the direct dependencies using the method described above,
and then run a `pip freeze > requirements.txt`.
It will generate a requirements.txt file containing all your dependencies
(including the transitive dependencies) pinned to their current versions.
Now you commit that requirements.txt.
From now on, you can consistently recreate your production environment by
`pip install -r requirements.txt`.

You may also use advanced dependency management tools to simplify the work flow.
For example,
[pip-tools](https://pypi.org/project/pip-tools).

2. Keep the dependencies updated.

The purpose of pinning dependencies in the production is not about
sticking with old versions forever.
It is about allowing you to control when to update what.
In the long run, you are still recommended to keep the dependencies updated because:

* The digital landscape is rife with threats.
Outdated dependencies are prime targets for malicious actors.
By staying updated, you fortify your project against known vulnerabilities
and significantly reduce the risk of exploitation.
* Software is rarely perfect. New versions of dependencies often include bug fixes,
improving the stability and performance of your application.
Ignoring updates means missing out on these enhancements.

You shall maintain a non-production environment,
periodically upgrade its dependencies to latest versions, test it out.
If the test passes, you can update the requirements.txt accordingly,
and deploy it to your production environment.

<!--
The content above is equivalent to
[section 2 of this document](https://www.geeksforgeeks.org/best-practices-for-managing-python-dependencies/#2-use-a-requirementstxt-file).
-->

## If you are maintaining a library

If you are maintaining a library (meaning it will be used by its downstream applications),
you shall avoid pinning your dependencies.
Instead, you shall declare your dependencies by range, such as `msal>=1.33, <2.0`.
The lower bound is the smallest version that started to provide the API you are using,
the upper bound is the version that is expected to contain breaking changes.