From ca21e087e7a5a46f70b71537fed2f6eb921d6ca8 Mon Sep 17 00:00:00 2001 From: Wenqi Li Date: Mon, 8 Aug 2022 13:07:32 +0100 Subject: [PATCH 1/4] set up a backward compatibility policy Signed-off-by: Wenqi Li --- CHANGELOG.md | 3 +-- CONTRIBUTING.md | 24 +++++++++++++++++------- 2 files changed, 18 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4a8dcfc60d..771dd9265b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,7 @@ # Changelog All notable changes to MONAI are documented in this file. -The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) -and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). +The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/). ## [Unreleased] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ac373bad75..6cfc56a979 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -283,10 +283,21 @@ for example, ``import monai.transforms.Spacing`` is the equivalent of ``monai.tr For string definition, [f-string](https://www.python.org/dev/peps/pep-0498/) is recommended to use over `%-print` and `format-print`. So please try to use `f-string` if you need to define any string object. #### Backwards compatibility -MONAI is currently under active development, and with major version zero (following the [Semantic Versioning](https://semver.org/)). -The backwards compatibility of the API is not always guaranteed at this initial development stage. -However, utility functions are provided in the `monai.utils.deprecated` modules to help users migrate to the new API. -The use of these functions is encouraged. +MONAI in general follows [PyTorch's policy for backward compatibility](https://github.com/pytorch/pytorch/wiki/PyTorch's-Python-Frontend-Backward-and-Forward-Compatibility-Policy). +Utility functions are provided in `monai.utils.deprecated` to help migrate from the deprecated to new APIs. The use of these utilities is encouraged. +The pull request [template contains checkboxes](https://github.com/Project-MONAI/MONAI/blame/dev/.github/pull_request_template.md#L11-L12) that +the contributor should use accordingly to clearly indicate breaking changes. + +The process of releasing backwards incompatible API changes is as follows: +1. discuss the breaking changes during pull requests or in dev meetings with a feature proposal if needed. +1. add a warning message in the upcoming release (version `X.Y`), the warning message should include a forecast of removing the deprecated API in: + 1. `X+1.0` -- major version `X+1` and minor version `0` the next major version if it's a significant change, + 1. `X.Y+2` -- major version `X` and minor version `Y+2` (the minor version after the next one), if it's a minor API change. + 1. Note that the versioning policy is similar to PyTorch's approach, however, does not follow [the semantic versioning](https://semver.org/). +1. add new test cases by extending the existing unit tests to cover both the deprecated and updated APIs. +1. collect feedback from the users during the subsequent few releases, and reconsider step 1 if needed. +1. before each release, review the deprecating APIs, and clean up the removed APIs described in step 2. + ### Submitting pull requests @@ -349,12 +360,11 @@ When major features are ready for a milestone, to prepare for a new release: - Merge `releasing/[version number]` to `dev`, this step must make sure that the tagging commit unchanged on `dev`. - Publish the release note. -Note that the release should be tagged with a [PEP440](https://www.python.org/dev/peps/pep-0440/) compliant -[semantic versioning](https://semver.org/spec/v2.0.0.html) number. +Note that the release should be tagged with a [PEP440](https://www.python.org/dev/peps/pep-0440/) compliant version number. If any error occurs during the release process, first check out a new hotfix branch from the `releasing/[version number]`, then make PRs to the `releasing/[version number]` to fix the bugs via the regular contribution procedure. If any error occurs after the release process, first check out a new hotfix branch from the `main` branch, -make a minor version release following the semantic versioning, for example, `releasing/0.1.1`. +make a patch version release following the semantic versioning, for example, `releasing/0.1.1`. Make sure the `releasing/0.1.1` is merged back into both `dev` and `main` and all the test pipelines succeed. From aa0783828b9c341a936c6cc95d32ca2a0d58f188 Mon Sep 17 00:00:00 2001 From: Wenqi Li Date: Mon, 8 Aug 2022 16:19:26 +0100 Subject: [PATCH 2/4] update based on comments Signed-off-by: Wenqi Li --- CONTRIBUTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6cfc56a979..94aaacd092 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -293,7 +293,9 @@ The process of releasing backwards incompatible API changes is as follows: 1. add a warning message in the upcoming release (version `X.Y`), the warning message should include a forecast of removing the deprecated API in: 1. `X+1.0` -- major version `X+1` and minor version `0` the next major version if it's a significant change, 1. `X.Y+2` -- major version `X` and minor version `Y+2` (the minor version after the next one), if it's a minor API change. - 1. Note that the versioning policy is similar to PyTorch's approach, however, does not follow [the semantic versioning](https://semver.org/). + 1. Note that the versioning policy is similar to PyTorch's approach which does not precisely follow [the semantic versioning](https://semver.org/) definition. + Major version numbers are instead used to represent major product version (which is currently not planned to be greater than 1), + minor version for both compatible and incompatible, and patch version for bug fixes. 1. add new test cases by extending the existing unit tests to cover both the deprecated and updated APIs. 1. collect feedback from the users during the subsequent few releases, and reconsider step 1 if needed. 1. before each release, review the deprecating APIs, and clean up the removed APIs described in step 2. From cdc7c40fed7e792239bde08df4b4aba881310836 Mon Sep 17 00:00:00 2001 From: Wenqi Li Date: Tue, 9 Aug 2022 20:35:07 +0100 Subject: [PATCH 3/4] update based on comments Signed-off-by: Wenqi Li --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 94aaacd092..0a686b3a11 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -296,6 +296,8 @@ The process of releasing backwards incompatible API changes is as follows: 1. Note that the versioning policy is similar to PyTorch's approach which does not precisely follow [the semantic versioning](https://semver.org/) definition. Major version numbers are instead used to represent major product version (which is currently not planned to be greater than 1), minor version for both compatible and incompatible, and patch version for bug fixes. + 1. when recommending new API to use in place of a deprecated API, the recommended version should + provide exact feature-like behaviour otherwise users will have a harder time migrating. 1. add new test cases by extending the existing unit tests to cover both the deprecated and updated APIs. 1. collect feedback from the users during the subsequent few releases, and reconsider step 1 if needed. 1. before each release, review the deprecating APIs, and clean up the removed APIs described in step 2. From d09d63093a57e60bba004e8282946408d00be778 Mon Sep 17 00:00:00 2001 From: Wenqi Li Date: Thu, 11 Aug 2022 11:31:15 +0100 Subject: [PATCH 4/4] update based on comments Signed-off-by: Wenqi Li --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0a686b3a11..1fef0789e3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -300,7 +300,7 @@ The process of releasing backwards incompatible API changes is as follows: provide exact feature-like behaviour otherwise users will have a harder time migrating. 1. add new test cases by extending the existing unit tests to cover both the deprecated and updated APIs. 1. collect feedback from the users during the subsequent few releases, and reconsider step 1 if needed. -1. before each release, review the deprecating APIs, and clean up the removed APIs described in step 2. +1. before each release, review the deprecating APIs and relevant tests, and clean up the removed APIs described in step 2.