From b312e796d69a89b795526fd7975f20b43d4b7447 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B0=A2=E6=98=95=E8=BE=B0?= <xiexinch@outlook.com>
Date: Mon, 9 Jan 2023 12:37:33 +0800
Subject: [PATCH] [Projects] Add 'Projects/' folder, and the first example
 project in 0.x (#2457)

## Motivation

Introducing new models and features into OpenMMLab's algorithm libraries
has long been complained to be troublesome due to the rigorous
requirements on code quality, which could hinder the fast iteration of
SOTA models and might discourage potential contributors from sharing
their latest outcome here.

Ref: https://github.com/open-mmlab/mmsegmentation/pull/2412

## Modification

This PR adds a new `projects/` folder, which will be a place for some
experimental models/features. Implementations inside might be not quite
perfect but already fine to produce some exciting results. We hope that
this PR can help us better embrace the contribution from our community.
We also add the first example project to illustrate what we expect a
good project to have.
---
 .github/workflows/build.yml                   |   2 +
 projects/README.md                            |   9 ++
 projects/example_project/README.md            | 129 ++++++++++++++++++
 ...mmy-r50-d8_4xb2-40k_cityscapes-512x1024.py |   6 +
 projects/example_project/dummy/__init__.py    |   4 +
 .../example_project/dummy/dummy_resnet.py     |  15 ++
 6 files changed, 165 insertions(+)
 create mode 100644 projects/README.md
 create mode 100644 projects/example_project/README.md
 create mode 100644 projects/example_project/configs/fcn_dummy-r50-d8_4xb2-40k_cityscapes-512x1024.py
 create mode 100644 projects/example_project/dummy/__init__.py
 create mode 100644 projects/example_project/dummy/dummy_resnet.py

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 2ab59cd3f..48c6c3569 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -8,6 +8,7 @@ on:
       - 'docker/**'
       - 'tools/**'
       - '**.md'
+      - 'projects/**'
 
   pull_request:
     paths-ignore:
@@ -17,6 +18,7 @@ on:
       - 'tools/**'
       - 'docs/**'
       - '**.md'
+      - 'projects/**'
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
diff --git a/projects/README.md b/projects/README.md
new file mode 100644
index 000000000..927defeb7
--- /dev/null
+++ b/projects/README.md
@@ -0,0 +1,9 @@
+# Projects
+
+Implementing new models and features into OpenMMLab's algorithm libraries could be troublesome due to the rigorous requirements on code quality, which could hinder the fast iteration of SOTA models and might discourage our members from sharing their latest outcomes here.
+
+And that's why we have this `Projects/` folder now, where some experimental features, frameworks and models are placed, only needed to satisfy the minimum requirement on the code quality, and can be used as standalone libraries. Users are welcome to use them if they [use MMSegmentation from source](https://mmsegmentation.readthedocs.io/en/latest/get_started.html#best-practices).
+
+Everyone is welcome to post their implementation of any great ideas in this folder! If you wish to start your own project, please go through the [example project](example_project/) for the best practice.
+
+Note: The core maintainers of MMSegmentation only ensure the results are reproducible and the code quality meets its claim at the time each project was submitted, but they may not be responsible for future maintenance. The original authors take responsibility for maintaining their own projects.
diff --git a/projects/example_project/README.md b/projects/example_project/README.md
new file mode 100644
index 000000000..3bb5df388
--- /dev/null
+++ b/projects/example_project/README.md
@@ -0,0 +1,129 @@
+# Dummy ResNet Wrapper
+
+This is an example README for community `projects/`. We have provided detailed explanations for each field in the form of html comments, which are visible when you read the source of this README file. If you wish to submit your project to our main repository, then all the fields in this README are mandatory for others to understand what you have achieved in this implementation. For more details, read our [contribution guide](https://github.com/open-mmlab/mmsegmentation/blob/master/.github/CONTRIBUTING.md) or approach us in [Discussions](https://github.com/open-mmlab/mmsegmentation/discussions).
+
+## Description
+
+<!-- Share any information you would like others to know. For example:
+
+Author: @xxx.
+
+This is an implementation of \[XXX\]. -->
+
+This project implements a dummy ResNet wrapper, which literally does nothing new but prints "hello world" during initialization.
+
+## Usage
+
+<!-- For a typical model, this section should contain the commands for training and testing. You are also suggested to dump your environment specification to env.yml by `conda env export > env.yml`. -->
+
+### Prerequisites
+
+- Python 3.7
+- PyTorch 1.6 or higher
+- [MIM](https://github.com/open-mmlab/mim) v0.33 or higher
+- [MMSegmentation](https://github.com/open-mmlab/mmsegmentation) v0.29.1 or higher
+
+All the commands below rely on the correct configuration of `PYTHONPATH`, which should point to the project's directory so that Python can locate the module files. In `example_project/` root directory, run the following line to add the current directory to `PYTHONPATH`:
+
+```shell
+export PYTHONPATH=`pwd`:$PYTHONPATH
+```
+
+### Training commands
+
+```shell
+mim train mmsegmentation configs/fcn_dummy-r50-d8_4xb2-40k_cityscapes-512x1024.py --work-dir work_dirs/dummy_resnet
+```
+
+To train on multiple GPUs, e.g. 8 GPUs, run the following command:
+
+```shell
+mim train mmsegmentation configs/fcn_dummy-r50-d8_4xb2-40k_cityscapes-512x1024.py --work-dir work_dirs/dummy_resnet --launcher pytorch --gpus 8
+```
+
+### Testing commands
+
+```shell
+mim test mmsegmentation configs/fcn_dummy-r50-d8_4xb2-40k_cityscapes-512x1024.py --work-dir work_dirs/dummy_resnet --checkpoint ${CHECKPOINT_PATH} --eval mIoU
+```
+
+<!-- List the results as usually done in other model's README. [Example](https://github.com/open-mmlab/mmsegmentation/tree/master/configs/fcn#results-and-models)
+
+You should claim whether this is based on the pre-trained weights, which are converted from the official release; or it's a reproduced result obtained from retraining the model in this project. -->
+
+| Method | Backbone | Crop Size | Lr schd | Mem (GB) | Inf time (fps) |  mIoU | mIoU(ms+flip) | config                                                             | download                                                                                                                                                                                                                                                                                                                           |
+| ------ | -------- | --------- | ------: | -------- | -------------- | ----: | ------------: | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FCN    | R-50-D8  | 512x1024  |   40000 | 5.7      | 4.17           | 72.25 |         73.36 | [config](configs/fcn_dummy-r50-d8_4xb2-40k_cityscapes-512x1024.py) | [model](https://download.openmmlab.com/mmsegmentation/v0.5/fcn/fcn_r50-d8_512x1024_40k_cityscapes/fcn_r50-d8_512x1024_40k_cityscapes_20200604_192608-efe53f0d.pth) \| [log](https://download.openmmlab.com/mmsegmentation/v0.5/fcn/fcn_r50-d8_512x1024_40k_cityscapes/fcn_r50-d8_512x1024_40k_cityscapes_20200604_192608.log.json) |
+
+## Citation
+
+<!-- You may remove this section if not applicable. -->
+
+```bibtex
+@misc{mmseg2020,
+    title={{MMSegmentation}: OpenMMLab Semantic Segmentation Toolbox and Benchmark},
+    author={MMSegmentation Contributors},
+    howpublished = {\url{https://github.com/open-mmlab/mmsegmentation}},
+    year={2020}
+}
+```
+
+## Checklist
+
+Here is a checklist illustrating a usual development workflow of a successful project, and also serves as an overview of this project's progress.
+
+<!-- The PIC (person in charge) or contributors of this project should check all the items that they believe have been finished, which will further be verified by codebase maintainers via a PR.
+
+OpenMMLab's maintainer will review the code to ensure the project's quality. Reaching the first milestone means that this project suffices the minimum requirement of being merged into 'projects/'. But this project is only eligible to become a part of the core package upon attaining the last milestone.
+
+Note that keeping this section up-to-date is crucial not only for this project's developers but the entire community, since there might be some other contributors joining this project and deciding their starting point from this list. It also helps maintainers accurately estimate time and effort on further code polishing, if needed.
+
+A project does not necessarily have to be finished in a single PR, but it's essential for the project to at least reach the first milestone in its very first PR. -->
+
+- [ ] Milestone 1: PR-ready, and acceptable to be one of the `projects/`.
+
+  - [ ] Finish the code
+
+  <!-- The code's design shall follow existing interfaces and convention. For example, each model component should be registered into `mmseg.registry.MODELS` and configurable via a config file. -->
+
+  - [ ] Basic docstrings & proper citation
+
+  <!-- Each major object should contain a docstring, describing its functionality and arguments. If you have adapted the code from other open-source projects, don't forget to cite the source project in docstring and make sure your behavior is not against its license. Typically, we do not accept any code snippet under GPL license. [A Short Guide to Open Source Licenses](https://medium.com/nationwide-technology/a-short-guide-to-open-source-licenses-cf5b1c329edd) -->
+
+  - [ ] Test-time correctness
+
+  <!-- If you are reproducing the result from a paper, make sure your model's inference-time performance matches that in the original paper. The weights usually could be obtained by simply renaming the keys in the official pre-trained weights. This test could be skipped though, if you are able to prove the training-time correctness and check the second milestone. -->
+
+  - [ ] A full README
+
+  <!-- As this template does. -->
+
+- [ ] Milestone 2: Indicates a successful model implementation.
+
+  - [ ] Training-time correctness
+
+  <!-- If you are reproducing the result from a paper, checking this item means that you should have trained your model from scratch based on the original paper's specification and verified that the final result matches the report within a minor error range. -->
+
+- [ ] Milestone 3: Good to be a part of our core package!
+
+  - [ ] Type hints and docstrings
+
+  <!-- Ideally *all* the methods should have [type hints](https://www.pythontutorial.net/python-basics/python-type-hints/) and [docstrings](https://google.github.io/styleguide/pyguide.html#381-docstrings). [Example](https://github.com/open-mmlab/mmsegmentation/blob/master/mmseg/utils/misc.py#L7) -->
+
+  - [ ] Unit tests
+
+  <!-- Unit tests for each module are required. [Example](https://github.com/open-mmlab/mmsegmentation/blob/master/tests/test_utils/test_misc.py) -->
+
+  - [ ] Code polishing
+
+  <!-- Refactor your code according to reviewer's comment. -->
+
+  - [ ] Metafile.yml
+
+  <!-- It will be parsed by MIM and Inferencer. [Example](https://github.com/open-mmlab/mmsegmentation/blob/master/configs/fcn/fcn.yml) -->
+
+- [ ] Move your modules into the core package following the codebase's file hierarchy structure.
+
+  <!-- In particular, you may have to refactor this README into a standard one. [Example](https://github.com/open-mmlab/mmsegmentation/blob/master/configs/fcn/README.md) -->
+
+- [ ] Refactor your modules into the core package following the codebase's file hierarchy structure.
diff --git a/projects/example_project/configs/fcn_dummy-r50-d8_4xb2-40k_cityscapes-512x1024.py b/projects/example_project/configs/fcn_dummy-r50-d8_4xb2-40k_cityscapes-512x1024.py
new file mode 100644
index 000000000..5c76c7ee0
--- /dev/null
+++ b/projects/example_project/configs/fcn_dummy-r50-d8_4xb2-40k_cityscapes-512x1024.py
@@ -0,0 +1,6 @@
+# Copyright (c) OpenMMLab. All rights reserved.
+_base_ = ['../../../configs/fcn/fcn_r50-d8_512x1024_40k_cityscapes.py']
+
+custom_imports = dict(imports=['projects.example_project.dummy'])
+
+model = dict(backbone=dict(type='DummyResNet'))
diff --git a/projects/example_project/dummy/__init__.py b/projects/example_project/dummy/__init__.py
new file mode 100644
index 000000000..bdd2416d3
--- /dev/null
+++ b/projects/example_project/dummy/__init__.py
@@ -0,0 +1,4 @@
+# Copyright (c) OpenMMLab. All rights reserved.
+from .dummy_resnet import DummyResNet
+
+__all__ = ['DummyResNet']
diff --git a/projects/example_project/dummy/dummy_resnet.py b/projects/example_project/dummy/dummy_resnet.py
new file mode 100644
index 000000000..baad9dcec
--- /dev/null
+++ b/projects/example_project/dummy/dummy_resnet.py
@@ -0,0 +1,15 @@
+# Copyright (c) OpenMMLab. All rights reserved.
+from mmseg.models import BACKBONES
+from mmseg.models.backbones import ResNetV1c
+
+
+@BACKBONES.register_module()
+class DummyResNet(ResNetV1c):
+    """Implements a dummy ResNet wrapper for demonstration purpose.
+    Args:
+        **kwargs: All the arguments are passed to the parent class.
+    """
+
+    def __init__(self, **kwargs) -> None:
+        print('Hello world!')
+        super().__init__(**kwargs)