|
@@ -1,3 +1,5 @@
|
|
|
|
+[简体中文](CONTRIBUTING_CN.md) | English
|
|
|
|
+
|
|
# PaddleRS Contribution Guide
|
|
# PaddleRS Contribution Guide
|
|
|
|
|
|
## Contribute Code
|
|
## Contribute Code
|
|
@@ -6,18 +8,18 @@ This guide starts with the necessary steps to contribute code to PaddleRS, and t
|
|
|
|
|
|
### 1 Code Contribution Steps
|
|
### 1 Code Contribution Steps
|
|
|
|
|
|
-PaddleRS uses [git](https://git-scm.com/doc) as a version control tool and is hosted on GitHub. This means that you need to be familiar with git before contributing code. And you need to be familiar with [pull request (PR)](https://docs.github.com/cn/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) based on the GitHub workflow.
|
|
|
|
|
|
+PaddleRS uses [Git](https://git-scm.com/doc) as a version control tool and is hosted on GitHub. This means that you need to be familiar with git before contributing code. And you need to be familiar with [pull request (PR)](https://docs.github.com/cn/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) based on the GitHub workflow.
|
|
|
|
|
|
The steps to contribute code to PaddleRS are as follows:
|
|
The steps to contribute code to PaddleRS are as follows:
|
|
|
|
|
|
-1. Fork the official PaddleRS repository on GitHub, clone the code locally, and pull the latest version of the develop branch.
|
|
|
|
-2. Write code according to [Dev Guide](dev/dev_guide.md) (it is recommended to develop on a new feature branch).
|
|
|
|
-3. Install pre-commit hooks to perform code style checks before each commit. Refer to [Code style specification](#3-Code style specification).
|
|
|
|
-4. Write unit tests for the new code and make sure all the tests are successful. Refer to [Test related steps](#4-Test related steps)。
|
|
|
|
-5. Create a new PR for your branch and ensure that the CLA protocol is signed and the CI/CE passes. After that, a PaddleRS team member will review the code you contributed.
|
|
|
|
|
|
+1. Fork the official PaddleRS repository on GitHub, clone the code locally, and pull the develop branch.
|
|
|
|
+2. Write code according to [Dev Guide](dev/dev_guide_en.md) (it is recommended to develop on a new feature branch).
|
|
|
|
+3. Install pre-commit hooks to perform code style checks before each commit. Refer to [Code style specification](#3-code-style-specification).
|
|
|
|
+4. Write unit tests for the new code and make sure all the tests are successful. Refer to [Test related steps](#4-test-related-steps)。
|
|
|
|
+5. Create a new PR for your branch and ensure that the CLA is signed and the CI/CE finish with no errors. After that, a PaddleRS team member will review the code you contributed.
|
|
6. Modify the code according to the review and resubmit it until PR is merged or closed.
|
|
6. Modify the code according to the review and resubmit it until PR is merged or closed.
|
|
|
|
|
|
-If you contribute code that uses a third-party library that PaddleRS does not currently rely on, please explain when you submit your PR. Also, you should explain why this third-party library should be used.
|
|
|
|
|
|
+If you contribute code that uses a third-party library that PaddleRS does not currently rely on, please explain when you submit your PR. Also, you should explain why this third-party library need to be used.
|
|
|
|
|
|
### 2 Self-Check on Added Files
|
|
### 2 Self-Check on Added Files
|
|
|
|
|
|
@@ -68,9 +70,9 @@ from paddlers.transforms import DecodeImg
|
|
|
|
|
|
### 3 Code Style Specification
|
|
### 3 Code Style Specification
|
|
|
|
|
|
-PaddleRS' code style specification is basically the same as the [Google Python Style specification](https://zh-google-styleguide.readthedocs.io/en/latest/google-python-styleguide/python_style_rules/), except that PaddleRS does not enforce the type annotation.(i.e. type hints, refer to [PEP 483](https://peps.python.org/pep-0483/) and [PEP 484](https://peps.python.org/pep-0484/)). Some of the important code style specifications are:
|
|
|
|
|
|
+PaddleRS' code style specification is basically the same as the [Google Python Style specification](https://zh-google-styleguide.readthedocs.io/en/latest/google-python-styleguide/python_style_rules/), except that PaddleRS does not enforce type annotation (i.e. type hints, refer to [PEP 483](https://peps.python.org/pep-0483/) and [PEP 484](https://peps.python.org/pep-0484/)). Some of the important code style specifications are:
|
|
|
|
|
|
-- Blank line: Two empty lines between top-level definitions (such as top-level function or class definitions). There is a blank line between the definitions of different methods within the class, and between the class name and the first method definition. Inside the function you need to be careful to add a blank line where there is a logical break.
|
|
|
|
|
|
+- Blank line: Two empty lines between top-level definitions (such as top-level function or class definitions). There should be a blank line between the definitions of different methods within the class. Inside the function you need to be careful to add a blank line where there is a logical break.
|
|
|
|
|
|
- Line length: No more than 80 characters per line (either code or comment), especially for lines in a docstring.
|
|
- Line length: No more than 80 characters per line (either code or comment), especially for lines in a docstring.
|
|
|
|
|
|
@@ -78,27 +80,27 @@ PaddleRS' code style specification is basically the same as the [Google Python S
|
|
|
|
|
|
- Exceptions: Throw and catch exceptions with as specific an exception type as possible, and almost never use the base class `Exception` (unless the purpose is to catch any exception of any type).
|
|
- Exceptions: Throw and catch exceptions with as specific an exception type as possible, and almost never use the base class `Exception` (unless the purpose is to catch any exception of any type).
|
|
|
|
|
|
-- Comments: All comments are written in English. All apis provided to users must have docstrings added and have at least two sections, "API Function Description" and "API Parameters". Surround a docstring with three double quotes `"""`. See the [Code Comment Specification](dev/docstring.md) for details on docstring writing.
|
|
|
|
|
|
+- Comments: All comments should be written in English. All apis provided to users must have docstrings added with at least two sections, "API Function Description" and "API Parameters". Surround a docstring with three double quotes `"""`. See the [Code Comment Specification](dev/docstring_en.md) for details on docstring writing.
|
|
|
|
|
|
- Naming: Variable names of different types apply the following case rules: module name: `module_name`; package name: `package_name`; class name: `ClassName`; method name: `method_name`; function name: `function_name`; name of a global constant (a variable whose value does not change during the running of the program) : `GLOBAL_CONSTANT_NAME`; global variable name: `global_var_name`; instance name: `instance_var_name`; function parameter name: `function_param_name`; local variable name: `local_var_name`.
|
|
- Naming: Variable names of different types apply the following case rules: module name: `module_name`; package name: `package_name`; class name: `ClassName`; method name: `method_name`; function name: `function_name`; name of a global constant (a variable whose value does not change during the running of the program) : `GLOBAL_CONSTANT_NAME`; global variable name: `global_var_name`; instance name: `instance_var_name`; function parameter name: `function_param_name`; local variable name: `local_var_name`.
|
|
|
|
|
|
### 4 Test Related Steps
|
|
### 4 Test Related Steps
|
|
|
|
|
|
-To ensure code quality, you need to write unit test scripts for the new functional components. Please read the steps for writing a single test according to your contribution.
|
|
|
|
|
|
+To ensure code quality, the contributor is required to add unit test cases for the new functional components. Please read the steps according to your contribution.
|
|
|
|
|
|
-#### 4.1 model Single Test
|
|
|
|
|
|
+#### 4.1 Unit Tests for Models
|
|
|
|
|
|
-1. Find the test case definition file corresponding to the task of the model in `tests/rs_models/`, for example, the change detection task corresponding to `tests/rs_models/test_cd_models.py`.
|
|
|
|
|
|
+1. Find the test case definition file corresponding to the task of the model in `tests/rs_models/`. For example, the change detection task corresponds to `tests/rs_models/test_cd_models.py`.
|
|
2. Define a test class for the new model that inherits from `Test{task name}Model` and sets its `MODEL_CLASS` property to the new model, following the example already in the file.
|
|
2. Define a test class for the new model that inherits from `Test{task name}Model` and sets its `MODEL_CLASS` property to the new model, following the example already in the file.
|
|
-3. Override the new test class's `test_specs()` method. This method sets `self.specs` to a list with each item in the list as a dictionary whose key-value pairs are used as configuration items for the constructor model. That is, each item in `self.specs` corresponds to a set of test cases, each of which tests the model constructed with a particular parameter.
|
|
|
|
|
|
+3. Override the new test class's `test_specs()` method. This method sets `self.specs` to a list with each item in the list as a dictionary, whose key-value pairs are used as configuration items for the constructor model. That is, each item in `self.specs` corresponds to a set of test cases, each of which tests the model constructed with a particular set of parameters.
|
|
|
|
|
|
-#### 4.2 Data Preprocessing/Data Augmentation Single Test
|
|
|
|
|
|
+#### 4.2 Unit Tests for Data Preprocessing/Data Augmentation Functions and Operators
|
|
|
|
|
|
-- If you write the data preprocessing/augmentation operator (inherited from `paddlers.transforms.operators.Transform`), all the necessary to construct the operator input parameters have default values, and the operator can handle any task, arbitrary band data, You need to add a new method to the `TestTransform` class in the `tests/transforms/test_operators.py` modulated on the `test_Resize()` or `test_RandomFlipOrRotate()` methods.
|
|
|
|
-- If you write an operator that only supports processing for a specific task or requires the number of bands in the input data, bind the operator `_InputFilter` in the `OP2FILTER` global variable after writing the test logic.
|
|
|
|
-- If you are writing a data preprocessing/data augmentation function(i.e. `paddlers/transforms/functions.py`), add a test class in `tests/transforms/test_functions.py` mimicking the existing example.
|
|
|
|
|
|
+- If you contribute an data preprocessing/augmentation operator (inherited from `paddlers.transforms.operators.Transform`), all the necessary input parameters to construct the operator have default values, and the operator can handle any task and arbitrary number of bands, then you need to add a new method to the `TestTransform` class in the `tests/transforms/test_operators.py`, mimicking the `test_Resize()` or `test_RandomFlipOrRotate()` methods.
|
|
|
|
+- If you contribute an operator that only supports processing for a specific task or has requirements for the number of bands in the input data, bind the operator with `_InputFilter` in `OP2FILTER`.
|
|
|
|
+- If you contribute a data preprocessing/data augmentation function (i.e. `paddlers/transforms/functions.py`), add a test class in `tests/transforms/test_functions.py` mimicking the existing example.
|
|
|
|
|
|
-#### 4.3 Tool Single Test
|
|
|
|
|
|
+#### 4.3 Unit Tests for Tools
|
|
|
|
|
|
1. Create a new file in the `tests/tools/` directory and name it `test_{tool name}.py`.
|
|
1. Create a new file in the `tests/tools/` directory and name it `test_{tool name}.py`.
|
|
2. Write the test case in the newly created script.
|
|
2. Write the test case in the newly created script.
|