Skip to content

Commit fab917e

Browse files
rayluorayluo
committed
Add dependency management suggestions
1 parent 37d9af5 commit fab917e

File tree

2 files changed

+107
-0
lines changed

2 files changed

+107
-0
lines changed

‎RELEASES.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Microsoft Identity SDK Versioning and Servicing FAQ
2+
3+
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.
4+
5+
## Semantic Versioning and API stability promises
6+
7+
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.
8+
9+
The semantics are: MAJOR.MINOR.PATCH (example 1.1.5)
10+
11+
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.
12+
13+
Example:
14+
Using NuGet, this ensures all 1.1.0 to 1.1.x updates are included when building your code, but not 1.2.
15+
16+
```
17+
<dependency
18+
id="MSALfordotNet"
19+
version="[1.1,1.2)"
20+
/>
21+
```
22+
23+
| Version | Description | Example |
24+
|:-------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------:|
25+
| 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) |
26+
| 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) |
27+
| 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) |
28+
29+
## Serviceability
30+
31+
When we release a new MINOR version, the previous MINOR version is abandoned.
32+
33+
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.
34+
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.
35+
36+
## Microsoft Authentication SDKs and Azure Active Directory
37+
38+
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.
39+
40+
We will respond to bugs quickly from our partners and customers submitted through GitHub and through our private alias ([email protected]) for security issues and update the PATCH version number. We will also submit a change summary for each PATCH number.
41+
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.

‎dependency-management.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Best Practices for Specifying Dependency Versions
2+
3+
The best practices for specifying dependency versions depend on
4+
whether you are maintaining an application or a library.
5+
6+
## If you are maintaining an application
7+
8+
There are two suggestions that you shall follow.
9+
10+
1. Pinning dependencies in a production environment.
11+
12+
This refers to explicitly declaring the exact version of your application's dependencies,
13+
including those of its dependencies (a.k.a. transitive dependencies).
14+
This ensures consistent and predictable deployments by preventing accidental upgrades that might introduce errors or regressions.
15+
16+
To achieve this, the steps can be different, based on the tooling you choose.
17+
For example, if you are using the common `pip` tool,
18+
you shall specify the version like this `pip install PackageName==x.y.z`,
19+
where x.y.z is the latest stable version that you have tested with your app.
20+
21+
Another trick is that you may start from a clean virtual environment,
22+
install all the direct dependencies using the method described above,
23+
and then run a `pip freeze > requirements.txt`.
24+
It will generate a requirements.txt file containing all your dependencies
25+
(including the trasitive dependencies) pinned to their current versions.
26+
Now you commit that requirements.txt.
27+
From now on, you can consistently recreate your production environment by
28+
`pip install -r requirements.txt`.
29+
30+
You may also use advance dependency management tools to simplify the work flow.
31+
For example,
32+
[pip-tools](https://pypi.org/project/pip-tools).
33+
34+
2. Keep the dependencies updated.
35+
36+
The purpose of pinning dependencies in the production is not about
37+
sticking with old versions forever.
38+
It is about allowing you to control when to update what.
39+
In the long run, you are still recommended to keep the dependencies updated because:
40+
41+
* The digital landscape is rife with threats.
42+
Outdated dependencies are prime targets for malicious actors.
43+
By staying updated, you fortify your project against known vulnerabilities
44+
and significantly reduce the risk of exploitation.
45+
* Software is rarely perfect. New versions of dependencies often include bug fixes,
46+
improving the stability and performance of your application.
47+
Ignoring updates means missing out on these enhancements.
48+
49+
You shall maintain a non-production environment,
50+
periodically upgrade its dependencies to latest versions, test it out.
51+
If the test passes, you can update the requirements.txt accordingly,
52+
and deploy it to your production environment.
53+
54+
<!--
55+
The content above is equivalent to
56+
[section 2 of this document](https://www.geeksforgeeks.org/best-practices-for-managing-python-dependencies/#2-use-a-requirementstxt-file).
57+
-->
58+
59+
## If you are maintaining a library
60+
61+
If you are maintaining a library (meaning it will be used by its downstream applications),
62+
you shall not pin your dependencies.
63+
Instead, you shall declare your dependencies by range, such as `msal>=1.33, <2.0`.
64+
The lower bound is the smallest version that started to provide the API you are using,
65+
the upper bound is the version that is expected to contain breaking changes.
66+

0 commit comments

Comments
 (0)