[Docs] Add maintenance plan and print deprecated message (#2357)

* [Docs] Add maintenance plan * Update maintenance plan * Update compatibility.md * Update README * resolve comments * Update README * Add warning info * update * fix typo
open-mmlab · Nov 1, 2022 · ff8e0c8 · ff8e0c8
1 parent e2c9fc4
commit ff8e0c8
Show file tree

Hide file tree

Showing 5 changed files with 148 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -31,6 +31,16 @@
 
 English | [简体中文](README_zh-CN.md)
 
+## Highlights
+
+The OpenMMLab team released a new generation of training engine [MMEngine](https://github.com/open-mmlab/mmengine) at the World Artificial Intelligence Conference on September 1, 2022. It is a foundational library for training deep learning models. Compared with MMCV, it provides a universal and powerful runner, an open architecture with a more unified interface, and a more customizable training process.
+
+At the same time, MMCV released [2.x](https://github.com/open-mmlab/mmcv/tree/2.x) release candidate version and will release 2.x official version on January 1, 2023.
+
+In version 2.x, it removed components related to the training process and added a data transformation module. Also, starting from 2.x, it renamed the package names **mmcv** to **mmcv-lite** and **mmcv-full** to **mmcv**. For details, see [Compatibility Documentation](docs/en/compatibility.md).
+
+MMCV will maintain both `1.x` and `2.x` versions. For details, see [Branch Maintenance Plan](README.md#branch-maintenance-plan).
+
 ## Introduction
 
 MMCV is a foundational library for computer vision research and it provides the following functionalities:
@@ -110,6 +120,16 @@ pip install -U openmim
 mim install mmcv
 ```
 
+## Branch Maintenance Plan
+
+MMCV currently has two branches, the master and 2.x branches, which go through the following three phases.
+
+| Phase                | Time                  | Branch                                                                                                          | description                                                                                                                                              |
+| -------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| RC Period            | 2022/9/1 - 2022.12.31 | Release candidate code (2.x version) will be released on 2.x branch. Default master branch is still 1.x version | Master and 2.x branches iterate normally                                                                                                                 |
+| Compatibility Period | 2023/1/1 - 2023.12.31 | **Default master branch will be switched to 2.x branch**, and 1.x branch will correspond to 1.x version         | We still maintain the old version 1.x, respond to user needs, but try not to introduce changes that break compatibility; master branch iterates normally |
+| Maintenance Period   | From 2024/1/1         | Default master branch corresponds to 2.x version and 1.x branch is 1.x version                                  | 1.x branch is in maintenance phase, no more new feature support; master branch is iterating normally                                                     |
+
 ## Supported projects
 
 - [MIM](https://github.com/open-mmlab/mim): MIM installs OpenMMLab packages.

diff --git a/README_zh-CN.md b/README_zh-CN.md
@@ -31,6 +31,14 @@
 
 [English](README.md) | 简体中文
 
+## Highlights
+
+OpenMMLab 团队于 2022 年 9 月 1 日在世界人工智能大会发布了新一代训练引擎 [MMEngine](https://github.com/open-mmlab/mmengine)，它是一个用于训练深度学习模型的基础库。相比于 MMCV，它提供了更高级且通用的训练器、接口更加统一的开放架构以及可定制化程度更高的训练流程。
+
+与此同时，MMCV 发布了 [2.x](https://github.com/open-mmlab/mmcv/tree/2.x) 预发布版本，并将于 2023 年 1 月 1 日发布 2.x 正式版本。在 2.x 版本中，它删除了和训练流程相关的组件，并新增了数据变换模块。另外，从 2.x 版本开始，重命名包名 **mmcv** 为 **mmcv-lite** 以及 **mmcv-full** 为 **mmcv**。详情见[兼容性文档](docs/zh_cn/compatibility.md)。
+
+MMCV 会同时维护 1.x 和 2.x 版本，详情见[分支维护计划](README_zh-CN.md#分支维护计划)。
+
 ## 简介
 
 MMCV 是一个面向计算机视觉的基础库，它提供了以下功能：
@@ -110,6 +118,16 @@ pip install -U openmim
 mim install mmcv
 ```
 
+## 分支维护计划
+
+MMCV 目前有两个分支，分别是 master 和 2.x 分支，它们会经历以下三个阶段：
+
+| 阶段   | 时间                  | 分支                                                         | 说明                                                                                                     |
+| ------ | --------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| 公测期 | 2022/9/1 - 2022.12.31 | 公测版代码发布在 2.x 分支；默认主分支 master 仍对应 1.x 版本 | master 和 2.x 分支正常进行迭代                                                                           |
+| 兼容期 | 2023/1/1 - 2023.12.31 | **切换默认主分支 master 为 2.x 版本**；1.x 分支对应 1.x 版本 | 保持对旧版本 1.x 的维护和开发，响应用户需求，但尽量不引进破坏旧版本兼容性的改动；master 分支正常进行迭代 |
+| 维护期 | 2024/1/1 - 待定       | 默认主分支 master 为 2.x 版本；1.x 分支对应 1.x 版本         | 1.x 分支进入维护阶段，不再进行新功能支持；master 分支正常进行迭代                                        |
+
 ## 支持的开源项目
 
 - [MIM](https://github.com/open-mmlab/mim): MIM 是 OpenMMlab 项目、算法、模型的统一入口

diff --git a/docs/en/compatibility.md b/docs/en/compatibility.md
@@ -1,3 +1,53 @@
+### v2.0.0rc1
+
+The OpenMMLab team released a new generation of training engine [MMEngine](https://github.com/open-mmlab/mmengine) at the World Artificial Intelligence Conference on September 1, 2022. It is a foundational library for training deep learning models. Compared with MMCV, it provides a universal and powerful runner, an open architecture with a more unified interface, and a more customizable training process.
+
+At the same time, MMCV released [2.x](https://github.com/open-mmlab/mmcv/tree/2.x) release candidate version and will release 2.x official version on January 1, 2023. In version 2.x, it has the following changes:
+
+(1) It removed the following components:
+
+- `mmcv.fileio` module, removed in PR [#2179](https://github.com/open-mmlab/mmcv/pull/2179). FileIO module from mmengine will be used wherever required.
+- `mmcv.runner`, `mmcv.parallel`, `mmcv. engine` and `mmcv.device`, removed in PR [#2216](https://github.com/open-mmlab/mmcv/pull/2216).
+- All classes in `mmcv.utils` (eg `Config` and `Registry`) and many functions, removed in PR [#2217](https://github.com/open-mmlab/mmcv/pull/2217). Only a few functions related to mmcv are reserved.
+- `mmcv.onnex`, `mmcv.tensorrt` modules and related functions, removed in PR [#2225](https://github.com/open-mmlab/mmcv/pull/2225).
+
+(2) It added the [`mmcv.transforms`](https://github.com/open-mmlab/mmcv/tree/2.x/mmcv/transforms) data transformation module.
+
+(3) It renamed the package name **mmcv** to **mmcv-lite** and **mmcv-full** to **mmcv** in PR [#2235](https://github.com/open-mmlab/mmcv/pull/2235). Also, change the default value of the environment variable `MMCV_WITH_OPS` from 0 to 1.
+
+<table class="docutils">
+<thead>
+  <tr>
+    <th align="center">MMCV < 2.0</th>
+    <th align="center">MMCV >= 2.0 </th>
+<tbody>
+  <tr>
+  <td valign="top">
+
+```bash
+# Contains ops, because the highest version of mmcv-full is less than 2.0.0, so there is no need to add version restrictions
+pip install mmcv-full -f xxxx
+
+# do not contain ops
+pip install "mmcv < 2.0.0"
+```
+
+</td>
+  <td valign="top">
+
+```bash
+# Contains ops
+pip install "mmcv>=2.0.0rc1" -f xxxx
+
+# Ops are not included, because the starting version of mmcv-lite is 2.0.0rc1, so there is no need to add version restrictions
+pip install mmcv-lite
+```
+
+</td>
+</tr>
+</thead>
+</table>
+
 ### v1.3.18
 
 Some ops have different implementations on different devices. Lots of macros and type checks are scattered in several files, which makes the code hard to maintain. For example:

diff --git a/docs/zh_cn/compatibility.md b/docs/zh_cn/compatibility.md
@@ -1,3 +1,53 @@
+### v2.0.0rc1
+
+OpenMMLab 团队于 2022 年 9 月 1 日在世界人工智能大会发布了新一代训练引擎 [MMEngine](https://github.com/open-mmlab/mmengine)，它是一个用于训练深度学习模型的基础库。相比于 MMCV，它提供了更高级且通用的训练器、接口更加统一的开放架构以及可定制化程度更高的训练流程。
+
+与此同时，MMCV 发布了 [2.x](https://github.com/open-mmlab/mmcv/tree/2.x) 预发布版本并将于 2023 年 1 月 1 日发布 2.x 正式版本。在 2.x 版本中，它有以下变化：
+
+（1）删除了以下组件：
+
+- `mmcv.fileio` 模块，删除于 PR [#2179](https://github.com/open-mmlab/mmcv/pull/2179)。在需要使用 FileIO 的地方使用 mmengine 中的 FileIO 模块
+- `mmcv.runner`、`mmcv.parallel`、`mmcv.engine` 和 `mmcv.device`，删除于 PR [#2216](https://github.com/open-mmlab/mmcv/pull/2216)
+- `mmcv.utils` 的所有类（例如 `Config` 和 `Registry`）和大部分函数，删除于 PR [#2217](https://github.com/open-mmlab/mmcv/pull/2217)，只保留少数和 mmcv 相关的函数
+- `mmcv.onnex`、`mmcv.tensorrt` 模块以及相关的函数，删除于 PR [#2225](https://github.com/open-mmlab/mmcv/pull/2225)
+
+（2）新增了 [`mmcv.transforms`](https://github.com/open-mmlab/mmcv/tree/2.x/mmcv/transforms) 数据变换模块
+
+（3）在 PR [#2235](https://github.com/open-mmlab/mmcv/pull/2235) 中将包名 **mmcv** 重命名为 **mmcv-lite**、 **mmcv-full** 重命名为 **mmcv**。此外，将环境变量 `MMCV_WITH_OPS` 的默认值从 0 改为 1
+
+<table class="docutils">
+<thead>
+  <tr>
+    <th align="center">MMCV < 2.0</th>
+    <th align="center">MMCV >= 2.0 </th>
+<tbody>
+  <tr>
+  <td valign="top">
+
+```bash
+# 包含算子，因为 mmcv-full 的最高版本小于 2.0.0，所以无需加版本限制
+pip install mmcv-full -f xxxx
+
+# 不包含算子
+pip install "mmcv < 2.0.0"
+```
+
+</td>
+  <td valign="top">
+
+```bash
+# 包含算子
+pip install "mmcv>=2.0.0rc1" -f xxxx
+
+# 不包含算子，因为 mmcv-lite 的起始版本为 2.0.0rc1，所以无需加版本限制
+pip install mmcv-lite
+```
+
+</td>
+</tr>
+</thead>
+</table>
+
 ### v1.3.18
 
 部分自定义算子对于不同的设备有不同实现，为此添加的大量宏命令与类型检查使得代码变得难以维护。例如：

diff --git a/mmcv/__init__.py b/mmcv/__init__.py
@@ -1,5 +1,7 @@
 # Copyright (c) OpenMMLab. All rights reserved.
 # flake8: noqa
+import warnings
+
 from .arraymisc import *
 from .fileio import *
 from .image import *
@@ -14,3 +16,11 @@
 # - parallel
 # - op
 # - device
+
+warnings.warn(
+    'On January 1, 2023, MMCV will release v2.0.0, in which it will remove '
+    'components related to the training process and add a data transformation '
+    'module. In addition, it will rename the package names mmcv to mmcv-lite '
+    'and mmcv-full to mmcv. '
+    'See https://github.com/open-mmlab/mmcv/blob/master/docs/en/compatibility.md '
+    'for more details.')