mirrors
/
mmocr
mirror of https://github.com/open-mmlab/mmocr.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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

* [Docs] Update docs after branch switching

* fix

* update

* update docs

* update
1.x
Tong Gao 2023-04-06 17:26:39 +08:00 committed by GitHub
parent 97efb04c50
commit a7e326f829
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
18 changed files with 219 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
README.md
View File

@ -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

26
README_zh-CN.md
View File

@ -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 .
```
## 快速入门

15
docs/en/get_started/install.md
View File

@ -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,7 +81,7 @@ pip install -v -e .
```shell
mim install 'mmocr>=1.0.0rc0'
mim install mmocr
```
@ -91,14 +89,17 @@ mim install 'mmocr>=1.0.0rc0'
`````
**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
```
````

11
docs/en/get_started/overview.md
View File

@ -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!

3
docs/en/index.rst
View File

@ -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

38
docs/en/migration/branches.md 100644
View File

@ -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.

19
docs/en/migration/news.md 100644
View File

@ -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!

3
docs/en/migration/overview.md
View File

@ -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.

25
docs/en/notes/branches.md 100644
View File

@ -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).
```

10
docs/en/notes/contribution_guide.md
View File

@ -13,11 +13,11 @@ Pull requests let you tell others about changes you have pushed to a branch in a
## Basic Workflow
1. Get the most recent codebase
2. Checkout a new branch from `main` or `dev-1.x` branch, depending on the version of the codebase you want to contribute to (see [Maintenance Plan](../migration/overview.md) for more details)
2. Checkout a new branch from `dev-1.x` branch, depending on the version of the codebase you want to contribute to.
3. Commit your changes ([Don't forget to use pre-commit hooks!](#3-commit-your-changes))
4. Push your changes and create a PR
5. Discuss and review your code
6. Merge your branch to `main` or `dev-1.x` branch
6. Merge your branch to `dev-1.x` branch
## Procedures in detail
@ -49,14 +49,14 @@ Pull requests let you tell others about changes you have pushed to a branch in a
git pull upstream dev-1.x
```
### 2. Checkout a new branch from the `main` branch or `dev-1.x` branch
### 2. Checkout a new branch from `dev-1.x` branch
```bash
git checkout -b branchname
```
```{tip}
To make commit history clear, we strongly recommend you checkout the `main` or `dev-1.x` branch before creating a new branch.
To make commit history clear, we strongly recommend you checkout the `dev-1.x` branch before creating a new branch.
```
### 3. Commit your changes
@ -103,7 +103,7 @@ To make commit history clear, we strongly recommend you checkout the `main` or `
- Modify your codes according to reviewers' suggestions and then push your changes.
### 6. Merge your branch to the `main` / `dev-1.x` branch and delete the branch
### 6. Merge your branch to `dev-1.x` branch and delete the branch
- After the PR is merged by the maintainer, you can delete the branch you created in your forked repository.

13
docs/zh_cn/get_started/install.md
View File

@ -50,8 +50,8 @@ conda install pytorch torchvision cpuonly -c pytorch
```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
```
**第二步** 安装 MMOCR.
@ -67,8 +67,6 @@ mim install 'mmdet>=3.0.0rc0'
```shell
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" 会让安装过程产生更详细的输出
# "-e" 会以可编辑的方式安装该代码库，你对该代码库所作的任何更改都会立即生效
@ -80,7 +78,7 @@ pip install -v -e .
```shell
mim install 'mmocr>=1.0.0rc0'
mim install mmocr
```
@ -88,14 +86,17 @@ mim install 'mmocr>=1.0.0rc0'
`````
**第三步（可选）** 如果你需要使用与 `albumentations` 有关的变换，比如 ABINet 数据流水线中的 `Albu`，请使用以下命令安装依赖：
**第三步（可选）** 如果你需要使用与 `albumentations` 有关的变换（如 ABINet 数据流水线中的 `Albu`），或需要构建文档、运行单元测试的依赖，请使用以下命令安装依赖：
`````{tabs}
````{group-tab} 源码安装
```shell
# 安装 albu
pip install -r requirements/albu.txt
# 安装文档、测试等依赖
pip install -r requirements.txt
```
````

8
docs/zh_cn/get_started/overview.md
View File

@ -9,4 +9,10 @@ MMOCR 是一个基于 [PyTorch](https://pytorch.org/) 和 [MMDetection](https://
随着 OpenMMLab 家族架构的整体升级， MMOCR 也相应地进行了大幅度的升级和修改。在这个大版本的更新中，MMOCR 中大量的冗余代码和重复实现被移除，多个关键方法的运行效率得到了提升，且整体框架设计上变得更为统一。考虑到该版本相较于 0.x 存在一些后向不兼容的修改，我们准备了一份详细的[迁移指南](../migration/overview.md)，并在里面列出了新版本所作出的所有改动和迁移所需的步骤，力求帮助熟悉旧版框架的用户尽快完成升级。尽管这可能需要一定时间，但我们相信由 MMOCR 和 OpenMMLab 生态系统整体带来的新特性会让这一切变得尤为值得。😊
接下来，请根据实际需求选择你需要阅读的章节。我们推荐初学者通过【[新手入门-快速运行](quick_run.md)】来熟悉 MMOCR 模型的调用，并从【用户指南】提供的案例中逐步掌握 MMOCR 的用法。中高级开发者则可以从【基础概念】中了解各个组件的背景、约定和推荐实现。同时，如果你在文档中未能找到需要的答案，欢迎通过 [issue](https://github.com/open-mmlab/mmocr/issues) 进行反馈，也可以通过提 [pull request](https://github.com/open-mmlab/mmocr/pulls) 参与至 MMOCR 的社区建设中来。
接下来，请根据实际需求选择你需要阅读的章节。
- 我们推荐初学者通过【[快速运行](quick_run.md)】来熟悉 MMOCR 的基本用法，并从【用户指南】提供的案例中逐步掌握 MMOCR 的用法。
- 中高级开发者则可以从【基础概念】中了解各个组件的背景、约定和推荐实现。
- 请阅读 [FAQ](faq.md) 来查找常见问题的答案。
- 同时，如果你在文档中未能找到需要的答案，欢迎通过 [issue](https://github.com/open-mmlab/mmocr/issues) 进行反馈。
- 我们也欢迎每一位用户成为贡献者！请阅读 [贡献指南](../notes/contribution_guide.md) 来了解如何为 MMOCR 做出贡献。

3
docs/zh_cn/index.rst
View File

@ -64,6 +64,7 @@
:maxdepth: 2
:caption: 其它
notes/branches.md
notes/contribution_guide.md
notes/changelog.md
@ -72,6 +73,8 @@
:caption: MMOCR 0.x 迁移指南
migration/overview.md
migration/news.md
migration/branches.md
migration/code.md
migration/dataset.md
migration/model.md

38
docs/zh_cn/migration/branches.md 100644
View File

@ -0,0 +1,38 @@
# 分支迁移
在早期阶段，MMOCR 有三个分支：`main`、`1.x` 和 `dev-1.x`。随着 MMOCR 1.0.0 正式版的发布，我们也重命名了其中一些分支，下面提供了新旧分支的对照。
- `main` 分支包括了 MMOCR 0.x（例如 v0.6.3）的代码。现在已经被重命名为 `0.x`。
- `1.x` 包含了 MMOCR 1.x（例如 1.0.0rc6）的代码。现在它是 `main` 分支的别名，会在 2023 的年中删除。
- `dev-1.x` 是 MMOCR 1.x 的开发分支。现在保持不变。
有关分支的更多信息，请查看[分支](../notes/branches.md)。
## 升级 `main` 分支时解决冲突
对于希望从旧 `main` 分支（包含 MMOCR 0.x 代码）升级的用户，代码可能会导致冲突。要避免这些冲突，请按照以下步骤操作：
1. 请 commit 在 `main` 上的所有更改（若有），并备份您当前的 `main` 分支。
```bash
git checkout main
git add --all
git commit -m 'backup'
git checkout -b main_backup
```
2. 从远程存储库获取最新更改。
```bash
git remote add openmmlab git@github.com:open-mmlab/mmocr.git
git fetch openmmlab
```
3. 通过运行 `git reset --hard openmmlab/main` 将 `main` 分支重置为远程存储库上的最新 `main` 分支。
```bash
git checkout main
git reset --hard openmmlab/main
```
按照这些步骤，您可以成功升级您的 `main` 分支。

19
docs/zh_cn/migration/news.md 100644
View File

@ -0,0 +1,19 @@
# MMOCR 1.x 更新汇总
此处列出了 MMOCR 1.x 相对于 0.x 版本的重大更新。
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. 更多的文档和教程：我们增加了更多的教程，降低用户的学习门槛。
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 支持了更多模型和模型种类。

3
docs/zh_cn/migration/overview.md
View File

@ -8,9 +8,10 @@ MMOCR 1.0 依赖于新的基础训练框架 [MMEngine](https://github.com/open-m
接下来，请根据你的实际需求，阅读需要的章节：
- 若需要了解 MMOCR 1.0 的主要变化，请阅读 [MMOCR 1.x 更新汇总](./news.md)
- 如果你需要把 0.x 版本中训练的模型直接迁移到 1.0 版本中使用，请阅读 [预训练模型迁移](./model.md)
- 如果你需要训练模型，请阅读 [数据集迁移](./dataset.md) 和 [数据增强迁移](./transforms.md)
- 如果你需要在 MMOCR 上进行开发，请阅读 [代码迁移](code.md) 和 [上游依赖库变更](https://github.com/open-mmlab/mmengine/tree/main/docs/zh_cn/migration)
- 如果你需要在 MMOCR 上进行开发，请阅读 [代码迁移](code.md) ，[分支迁移](branches.md) 和 [上游依赖库变更](https://github.com/open-mmlab/mmengine/tree/main/docs/zh_cn/migration)
如下图所示，MMOCR 1.x 版本的维护计划主要分为三个阶段，即“公测期”，“兼容期”以及“维护期”。对于旧版本，我们将不再增加主要新功能。因此，我们强烈建议用户尽早迁移至 MMOCR 1.x 版本。

25
docs/zh_cn/notes/branches.md 100644
View File

@ -0,0 +1,25 @@
# 分支
本文档旨在全面解释 MMOCR 中每个分支的目的和功能。
## 分支概述
### 1. `main`
`main` 分支是 MMOCR 项目的默认分支。它包含了 MMOCR 的最新稳定版本，目前包含了 MMOCR 1.x（例如 v1.0.0）的代码。`main` 分支确保用户能够使用最新和最可靠的软件版本。
### 2. `dev-1.x`
`dev-1.x` 分支用于开发 MMOCR 的下一个版本。此分支将在发版前进行依赖性测试，通过的提交将会合成到新版本中，并被发布到 `main` 分支。通过设置单独的开发分支，项目可以在不影响 `main` 分支稳定性的情况下继续发展。**所有 PR 应合并到 `dev-1.x` 分支。**
### 3. `0.x`
`0.x` 分支用作 MMOCR 0.x（例如 v0.6.3）的存档。此分支将不再积极接受更新或改进，但它仍可作为历史参考，或供尚未升级到 MMOCR 1.x 的用户使用。
### 4. `1.x`
它是 `main` 分支的别名，旨在实现从兼容性时期平稳过渡。它将在 2023 年的年中删除。
```{note}
分支映射在 2023.04.06 发生了变化。有关旧分支映射和迁移指南，请参阅[分支迁移指南](../migration/branches.md)。
```

10
docs/zh_cn/notes/contribution_guide.md
View File

@ -13,11 +13,11 @@ OpenMMLab 欢迎所有人参与我们项目的共建。本文档将指导您如
## 基本的工作流：
1. 获取最新的代码库
2. 根据你打算贡献的版本，从最新的 `main` 或 `dev-1.x` 分支创建分支进行开发（可以阅读我们的[维护计划](../migration/overview.md)以获知详情）
3. 提交修改 ([不要忘记使用 pre-commit hooks!](#))
2. 从最新的 `dev-1.x` 分支创建分支进行开发
3. 提交修改 ([不要忘记使用 pre-commit hooks!](#3-提交你的修改))
4. 推送你的修改并创建一个 `拉取请求`
5. 讨论、审核代码
6. 将开发分支合并到 `main` 或 `dev-1.x` 分支
6. 将开发分支合并到 `dev-1.x` 分支
## 具体步骤
@ -49,14 +49,14 @@ OpenMMLab 欢迎所有人参与我们项目的共建。本文档将指导您如
git pull upstream dev-1.x
```
### 2. 从 `main` 或 `dev-1.x` 分支创建一个新的开发分支
### 2. 从 `dev-1.x` 分支创建一个新的开发分支
```bash
git checkout -b branchname
```
```{tip}
为了保证提交历史清晰可读，我们强烈推荐您先切换到 `main` 或 `dev-1.x` 分支，再创建新的分支。
为了保证提交历史清晰可读，我们强烈推荐您先切换到 `dev-1.x` 分支，再创建新的分支。
```
### 3. 提交你的修改