[Docs] Update docs after branch switching (#1834)

* [Docs] Update docs after branch switching

* fix

* update

* update docs

* update

README.md

@@ -62,9 +62,7 @@ English | [简体中文](README_zh-CN.md)
 
 ## Latest Updates
 
-**The default branch has been switched to `1.x` from `main`, and we encourage
-users to migrate to the latest version, though it comes with some cost. Please refer to [Migration Guide](https://mmocr.readthedocs.io/en/dev-1.x/migration/overview.html) for more
-details.**
+**The default branch is now `main` and the code on the branch has been switched to v1.0.0. The old `main` branch (v0.6.3) code now exists on the `0.x` branch.** If you have been using the `main` branch and encounter upgrade issues, please read the [Migration Guide](https://mmocr.readthedocs.io/en/dev-1.x/migration/overview.html) and notes on [Branches](https://mmocr.readthedocs.io/en/dev-1.x/migration/branches.html) .
 
 v1.0.0rc6 was released in 2023-03-07.
 
@@ -106,24 +104,6 @@ The main branch works with **PyTorch 1.6+**.
 
   The toolbox provides a comprehensive set of utilities which can help users assess the performance of models. It includes visualizers which allow visualization of images, ground truths as well as predicted bounding boxes, and a validation tool for evaluating checkpoints during training.  It also includes data converters to demonstrate how to convert your own data to the annotation files which the toolbox supports.
 
-## What's New in MMOCR 1.0
-
-1. **New engines**. MMOCR 1.x is based on [MMEngine](https://github.com/open-mmlab/mmengine), which provides a general and powerful runner that allows more flexible customizations and significantly simplifies the entrypoints of high-level interfaces.
-
-2. **Unified interfaces**. As a part of the OpenMMLab 2.0 projects, MMOCR 1.x unifies and refactors the interfaces and internal logics of train, testing, datasets, models, evaluation, and visualization. All the OpenMMLab 2.0 projects share the same design in those interfaces and logics to allow the emergence of multi-task/modality algorithms.
-
-3. **Cross project calling**. Benefiting from the unified design, you can use the models implemented in other OpenMMLab projects, such as MMDet. We provide an example of how to use MMDetection's Mask R-CNN through `MMDetWrapper`. Check our documents for more details. More wrappers will be released in the future.
-
-4. **Stronger visualization**. We provide a series of useful tools which are mostly based on brand-new visualizers. As a result, it is more convenient for the users to explore the models and datasets now.
-
-5. **More documentation and tutorials**. We add a bunch of documentation and tutorials to help users get started more smoothly. Read it [here](https://mmocr.readthedocs.io/en/dev-1.x/).
-
-6. **One-stop Dataset Preparaion**. Multiple datasets are instantly ready with only one line of command, via our [Dataset Preparer](https://mmocr.readthedocs.io/en/dev-1.x/user_guides/data_prepare/dataset_preparer.html).
-
-7. **Embracing more `projects/`**: We now introduce `projects/` folder, where some experimental features, frameworks and models can be placed, only needed to satisfy the minimum requirement on the code quality. Everyone is welcome to post their implementation of any great ideas in this folder! Learn more from our [example project](https://github.com/open-mmlab/mmocr/blob/dev-1.x/projects/example_project/).
-
-8. **More models**. MMOCR 1.0 supports more tasks and more state-of-the-art models!
-
 ## Installation
 
 MMOCR depends on [PyTorch](https://pytorch.org/), [MMEngine](https://github.com/open-mmlab/mmengine), [MMCV](https://github.com/open-mmlab/mmcv) and [MMDetection](https://github.com/open-mmlab/mmdetection).
@@ -134,13 +114,9 @@ Please refer to [Install Guide](https://mmocr.readthedocs.io/en/dev-1.x/get_star
 conda create -n open-mmlab python=3.8 pytorch=1.10 cudatoolkit=11.3 torchvision -c pytorch -y
 conda activate open-mmlab
 pip3 install openmim
-mim install mmengine
-mim install 'mmcv>=2.0.0rc1'
-mim install 'mmdet>=3.0.0rc0'
 git clone https://github.com/open-mmlab/mmocr.git
 cd mmocr
-git checkout 1.x
-pip3 install -e .
+mim install -e .
 ```
 
 ## Get Started

README_zh-CN.md

@@ -63,7 +63,7 @@
 
 ## 近期更新
 
-**默认分支已经从 `main` 切换到 `1.x`。我们鼓励用户迁移到最新版本，请参考 [迁移指南](https://mmocr.readthedocs.io/zh_CN/dev-1.x/migration/overview.html) 以了解更多细节。**
+**默认分支目前为 `main`，且分支上的代码已经切换到 v1.0.0 版本。旧版 `main` 分支（v0.6.3）的代码现存在 `0.x` 分支上。** 如果您一直在使用 `main` 分支，并遇到升级问题，请阅读 [迁移指南](https://mmocr.readthedocs.io/zh_CN/dev-1.x/migration/overview.html) 和 [分支说明](https://mmocr.readthedocs.io/zh_CN/dev-1.x/migration/branches.html) 。
 
 最新的版本 v1.0.0rc6 于 2023-03-07 发布。
 
@@ -111,24 +111,6 @@ MMOCR 的模块化设计使用户可以定义自己的优化器，数据预处
 
 该工具箱提供了一套全面的实用程序，可以帮助用户评估模型的性能。它包括可对图像，标注的真值以及预测结果进行可视化的可视化工具，以及用于在训练过程中评估模型的验证工具。它还包括数据转换器，演示了如何将用户自建的标注数据转换为 MMOCR 支持的标注文件。
 
-## MMOCR 1.0 更新汇总
-
-1. 架构升级：MMOCR 1.x 是基于 [MMEngine](https://github.com/open-mmlab/mmengine)，提供了一个通用的、强大的执行器，允许更灵活的定制，提供了统一的训练和测试入口。
-
-2. 统一接口：MMOCR 1.x 统一了数据集、模型、评估和可视化的接口和内部逻辑。支持更强的扩展性。
-
-3. 跨项目调用：受益于统一的设计，你可以使用其他OpenMMLab项目中实现的模型，如MMDet。 我们提供了一个例子，说明如何通过MMDetWrapper使用MMDetection的Mask R-CNN。查看我们的文档以了解更多细节。更多的包装器将在未来发布。
-
-4. 更强的可视化：我们提供了一系列可视化工具， 用户现在可以更方便可视化数据。
-
-5. 更多的文档和教程：我们增加了更多的教程，降低用户的学习门槛。详见[教程](https://mmocr.readthedocs.io/zh_CN/dev-1.x/)。
-
-6. 一站式数据准备：准备数据集已经不再是难事。使用我们的 [Dataset Preparer](https://mmocr.readthedocs.io/zh_CN/dev-1.x/user_guides/data_prepare/dataset_preparer.html)，一行命令即可让多个数据集准备就绪。
-
-7. 拥抱更多 `projects/`: 我们推出了 `projects/` 文件夹，用于存放一些实验性的新特性、框架和模型。我们对这个文件夹下的代码规范不作过多要求，力求让社区的所有想法第一时间得到实现和展示。请查看我们的[样例 project](https://github.com/open-mmlab/mmocr/blob/dev-1.x/projects/example_project/) 以了解更多。
-
-8. 更多新模型：MMOCR 1.0 支持了更多模型和模型种类。
-
 ## 安装
 
 MMOCR 依赖 [PyTorch](https://pytorch.org/), [MMEngine](https://github.com/open-mmlab/mmengine), [MMCV](https://github.com/open-mmlab/mmcv) 和 [MMDetection](https://github.com/open-mmlab/mmdetection)，以下是安装的简要步骤。
@@ -138,13 +120,9 @@ MMOCR 依赖 [PyTorch](https://pytorch.org/), [MMEngine](https://github.com/open
 conda create -n open-mmlab python=3.8 pytorch=1.10 cudatoolkit=11.3 torchvision -c pytorch -y
 conda activate open-mmlab
 pip3 install openmim
-mim install mmengine
-mim install 'mmcv>=2.0.0rc1'
-mim install 'mmdet>=3.0.0rc0'
 git clone https://github.com/open-mmlab/mmocr.git
 cd mmocr
-git checkout 1.x
-pip3 install -e .
+mim install -e .
 ```
 
 ## 快速入门

docs/en/get_started/install.md

@@ -50,15 +50,15 @@ We recommend that users follow our best practices to install MMOCR. However, the
 ```shell
 pip install -U openmim
 mim install mmengine
-mim install 'mmcv>=2.0.0rc1'
-mim install 'mmdet>=3.0.0rc0'
+mim install mmcv
+mim install mmdet
 ```
 
 **Step 1.** Install MMOCR.
 
 If you wish to run and develop MMOCR directly, install it from **source** (recommended).
 
-If you use MMOCR as a dependency or third-party package, install it with **MIM**.
+If you use MMOCR as a dependency or third-party package, install it via **MIM**.
 
 `````{tabs}
 
@@ -68,8 +68,6 @@ If you use MMOCR as a dependency or third-party package, install it with **MIM**
 
 git clone https://github.com/open-mmlab/mmocr.git
 cd mmocr
-git checkout 1.x
-pip install -r requirements.txt
 pip install -v -e .
 # "-v" increases pip's verbosity.
 # "-e" means installing the project in editable mode,
@@ -83,22 +81,25 @@ pip install -v -e .
 
 ```shell
 
-mim install 'mmocr>=1.0.0rc0'
+mim install mmocr
 
 ```
 
 ````
 
 `````
 
-**Step 2. (Optional)** If you wish to use any transform involving `albumentations` (For example, `Albu` in ABINet's pipeline), install the dependency using the following command:
+**Step 2. (Optional)** If you wish to use any transform involving `albumentations` (For example, `Albu` in ABINet's pipeline), or any dependency for building documentation or running unit tests, please install the dependency using the following command:
 
 `````{tabs}
 
 ````{group-tab} Install from Source
 
 ```shell
+# install albu
 pip install -r requirements/albu.txt
+# install the dependencies for building documentation and running unit tests
+pip install -r requirements.txt
 ```
 
 ````

docs/en/get_started/overview.md

@@ -7,7 +7,14 @@ MMOCR is an open source toolkit based on [PyTorch](https://pytorch.org/) and [MM
 - **Various Useful Tools**: MMOCR provides a number of analysis tools, including visualizers, validation scripts, evaluators, etc., to help users troubleshoot, finetune or compare models.
 - **Powered by [OpenMMLab](https://openmmlab.com/)**: Like other algorithm libraries in OpenMMLab family, MMOCR follows OpenMMLab's rigorous development guidelines and interface conventions, significantly reducing the learning cost of users familiar with other projects in OpenMMLab family. In addition, benefiting from the unified interfaces among OpenMMLab, you can easily call the models implemented in other OpenMMLab projects (e.g. MMDetection) in MMOCR, facilitating cross-domain research and real-world applications.
 
-Together with the release of OpenMMLab 2.0, MMOCR 1.0.0 has made significant BC-breaking changes, resulting in less code redundancy, higher code efficiency and an overall more systematic and consistent design.
+Together with the release of OpenMMLab 2.0, MMOCR now also comes to its 1.0.0 version, which has made significant BC-breaking changes, resulting in less code redundancy, higher code efficiency and an overall more systematic and consistent design.
+
 Considering that there are some backward incompatible changes in this version compared to 0.x, we have prepared a detailed [migration guide](../migration/overview.md). It lists all the changes made in the new version and the steps required to migrate. We hope this guide can help users familiar with the old framework to complete the upgrade as quickly as possible. Though this may take some time, we believe that the new features brought by MMOCR and the OpenMMLab ecosystem will make it all worthwhile. 😊
 
-Next, please read the section according to your actual needs. We recommend that beginners go through [Get Started-Quick Run](quick_run.py) to get familiar with MMOCR and master the usage of MMOCR by reading the examples in \[Usesr Guide\]. Intermediate and advanced developers are suggested to learn the background, conventions, and recommended implementations of each component from \[Basic Concepts\]. In addition, if you can't find the answers you need in the documentation, feel free to raise an [issue](https://github.com/open-mmlab/mmocr/issues) or even submit a [pull request](https://github.com/open-mmlab/) mmocr/pulls) to participate in the construction of the MMOCR community.
+Next, please read the section according to your actual needs.
+
+- We recommend that beginners go through [Quick Run](quick_run.md) to get familiar with MMOCR and master the usage of MMOCR by reading the examples in **User Guides**.
+- Intermediate and advanced developers are suggested to learn the background, conventions, and recommended implementations of each component from **Basic Concepts**.
+- Read our [FAQ](faq.md) to find answers to frequently asked questions.
+- If you can't find the answers you need in the documentation, feel free to raise an [issue](https://github.com/open-mmlab/mmocr/issues).
+- Everyone is welcome to be a contributor! Read the [contribution guide](../notes/contribution_guide.md) to learn how to contribute to MMOCR!

docs/en/index.rst

@@ -64,6 +64,7 @@ You can switch between English and Chinese in the lower-left corner of the layou
    :maxdepth: 2
    :caption: Notes
 
+   notes/branches.md
    notes/contribution_guide.md
    notes/changelog.md
 
@@ -72,6 +73,8 @@ You can switch between English and Chinese in the lower-left corner of the layou
    :caption: Migrating from MMOCR 0.x
 
    migration/overview.md
+   migration/news.md
+   migration/branches.md
    migration/code.md
    migration/dataset.md
    migration/model.md

docs/en/migration/branches.md

@@ -0,0 +1,38 @@
+# Branch Migration
+
+At an earlier stage, MMOCR had three branches: `main`, `1.x`, and `dev-1.x`. Some of these branches have been renamed together with the official MMOCR 1.0.0 release, and here is the changelog.
+
+- `main` branch housed the code for MMOCR 0.x (e.g., v0.6.3). Now it has been renamed to `0.x`.
+- `1.x` contained the code for MMOCR 1.x (e.g., 1.0.0rc6). Now it is an alias of `main`, and will be removed in mid 2023.
+- `dev-1.x` was the development branch for MMOCR 1.x. Now it remains unchanged.
+
+For more information about the branches, check out [branches](../notes/branches.md).
+
+## Resolving Conflicts When Upgrading the `main` branch
+
+For users who wish to upgrade from the old `main` branch that has the code for MMOCR 0.x, the non-fast-forwarded-able nature of the upgrade may cause conflicts. To resolve these conflicts, follow the steps below:
+
+1. Commit all the changes you have on `main` if you have any. Backup your current `main` branch by creating a copy.
+
+   ```bash
+   git checkout main
+   git add --all
+   git commit -m 'backup'
+   git checkout -b main_backup
+   ```
+
+2. Fetch the latest changes from the remote repository.
+
+   ```bash
+   git remote add openmmlab git@github.com:open-mmlab/mmocr.git
+   git fetch openmmlab
+   ```
+
+3. Reset the `main` branch to the latest `main` branch on the remote repository by running `git reset --hard openmmlab/main`.
+
+   ```bash
+   git checkout main
+   git reset --hard openmmlab/main
+   ```
+
+By following these steps, you can successfully upgrade your `main` branch.

docs/en/migration/news.md

@@ -0,0 +1,19 @@
+# What's New in MMOCR 1.x
+
+Here are some highlights of MMOCR 1.x compared to 0.x.
+
+1. **New engines**. MMOCR 1.x is based on [MMEngine](https://github.com/open-mmlab/mmengine), which provides a general and powerful runner that allows more flexible customizations and significantly simplifies the entrypoints of high-level interfaces.
+
+2. **Unified interfaces**. As a part of the OpenMMLab 2.0 projects, MMOCR 1.x unifies and refactors the interfaces and internal logics of train, testing, datasets, models, evaluation, and visualization. All the OpenMMLab 2.0 projects share the same design in those interfaces and logics to allow the emergence of multi-task/modality algorithms.
+
+3. **Cross project calling**. Benefiting from the unified design, you can use the models implemented in other OpenMMLab projects, such as MMDet. We provide an example of how to use MMDetection's Mask R-CNN through `MMDetWrapper`. Check our documents for more details. More wrappers will be released in the future.
+
+4. **Stronger visualization**. We provide a series of useful tools which are mostly based on brand-new visualizers. As a result, it is more convenient for the users to explore the models and datasets now.
+
+5. **More documentation and tutorials**. We add a bunch of documentation and tutorials to help users get started more smoothly.
+
+6. **One-stop Dataset Preparaion**. Multiple datasets are instantly ready with only one line of command, via our [Dataset Preparer](https://mmocr.readthedocs.io/en/dev-1.x/user_guides/data_prepare/dataset_preparer.html).
+
+7. **Embracing more `projects/`**: We now introduce `projects/` folder, where some experimental features, frameworks and models can be placed, only needed to satisfy the minimum requirement on the code quality. Everyone is welcome to post their implementation of any great ideas in this folder! Learn more from our [example project](https://github.com/open-mmlab/mmocr/blob/dev-1.x/projects/example_project/).
+
+8. **More models**. MMOCR 1.0 supports more tasks and more state-of-the-art models!

docs/en/migration/overview.md

@@ -8,9 +8,10 @@ MMOCR 1.0 depends on the new foundational library for training deep learning mod
 
 Next, please read the sections according to your requirements.
 
+- Read [What's new in MMOCR 1.x](./news.md) to learn about the new features and changes in MMOCR 1.x.
 - If you want to migrate a model trained in version 0.x to use it directly in version 1.0, please read [Pretrained Model Migration](./model.md).
 - If you want to train the model, please read [Dataset Migration](./dataset.md) and [Data Transform Migration](./transforms.md).
-- If you want to develop on MMOCR, please read [Code Migration](code.md) and [Upstream Library Changes](https://github.com/open-mmlab/mmengine/tree/main/docs/en/migration).
+- If you want to develop on MMOCR, please read [Code Migration](code.md), [Branch Migration](branches.md) and [Upstream Library Changes](https://github.com/open-mmlab/mmengine/tree/main/docs/en/migration).
 
 As shown in the following figure, the maintenance plan of MMOCR 1.x version is mainly divided into three stages, namely "RC Period", "Compatibility Period" and "Maintenance Period". For old versions, we will no longer add major new features. Therefore, we strongly recommend users to migrate to MMOCR 1.x version as soon as possible.
 

docs/en/notes/branches.md

@@ -0,0 +1,25 @@
+# Branches
+
+This documentation aims to provide a comprehensive understanding of the purpose and features of each branch in MMOCR.
+
+## Branch Overview
+
+### 1. `main`
+
+The `main` branch serves as the default branch for the MMOCR project. It contains the latest stable version of MMOCR, currently housing the code for MMOCR 1.x (e.g. v1.0.0). The `main` branch ensures users have access to the most recent and reliable version of the software.
+
+### 2. `dev-1.x`
+
+The `dev-1.x` branch is dedicated to the development of the next major version of MMOCR. This branch will routinely undergo reliance tests, and the passing commits will be squashed in a release and published to the `main` branch. By having a separate development branch, the project can continue to evolve without impacting the stability of the `main` branch. **All the PRs should be merged into the `dev-1.x` branch.**
+
+### 3. `0.x`
+
+The `0.x` branch serves as an archive for MMOCR 0.x (e.g. v0.6.3). This branch will no longer actively receive updates or improvements, but it remains accessible for historical reference or for users who have not yet upgraded to MMOCR 1.x.
+
+### 3. `1.x`
+
+It's an alias of `main` branch, which is intended for a smooth transition from the compatibility period. It will be removed in mid 2023.
+
+```{note}
+The branches mapping has been changed in 2023.04.06. For the legacy branches mapping and the guide for migration, please refer to the [branch migration guide](../migration/branches.md).
+```