Skip to content

[doc] package version rule #21490

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
msyyc merged 1 commit into from
Oct 29, 2021
Merged

[doc] package version rule #21490

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
44 changes: 44 additions & 0 deletions doc/dev/package_version/package_version_rule.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
This file claims the rules how Python decide next version number for package.

The package version contains two part:
1. the package is preview or stable?
2. version number

# How to judge preview or stable?
Python SDK is generated with [swagger](https://github.com/Azure/azure-rest-api-specs), so if swagger content is preview,
the package is preview; if swagger content is stable, the package is stable.

(1) For single api package(for example: [datadog](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/datadog)),
as long as the current tag is preview, the package version should be preview

(2) For multi api package(for example: [network](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/network/azure-mgmt-network)),
there will be `DEFAULT_API_VERSION`(for example: [`DEFAULT_API_VERSION` of network](https://github.com/Azure/azure-sdk-for-python/blob/59709af16b7cd29a51d562137bc5bbfdf53f9327/sdk/network/azure-mgmt-network/azure/mgmt/network/_network_management_client.py#L60)).
As long as it is preview, then the package version is preview.

(note1: If the name of tag contains 'preview' or the tag contains files of 'preview' folder, then the tag is preview tag.
For exampe: [preview tag](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/compute/resource-manager#tag-package-2021-06-01-preview))

(note2: If the api-version contains 'preview', then it is preview api-version. for example: [preview api-version](https://github.com/Azure/azure-rest-api-specs/blob/69eacf00a36d565d3220d5dd6f4a5293664f1ae9/specification/network/resource-manager/Microsoft.Network/preview/2015-05-01-preview/network.json#L6))

(note3: The difference about single api and multi api, please see the detailed file)

(note4: preview package version contains `b`, for example: `1.0.0b1`)

# How to decide next version number
1\. If current version is preview version, the new tag is preview tag, then next version is `x.x.xbx+1`

2\. If current version is stable version, the new tag is stable tag, then :
* if there is breaking change, next version is `x+1.x.x`
* if there is new feature but no breaking change, next version is `x.x+1.x`
* if there is only bugfix, next version is `x.x.x+1`

3\. If current version is stable version, the new tag is preview tag, calculate version number according to `2`
and then append `b1` in the result


According to the up rules, we could summarize all the possibilities in the following table:

![img.png](version_summary.png)

(`-` means that this item doesn't influence result)

Binary file added doc/dev/package_version/version summary.xlsx
View file
Open in desktop
Binary file not shown.
Binary file added doc/dev/package_version/version_summary.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.