diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 9aa3ffcaef9..fe946217933 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -23,6 +23,10 @@ repos: examples/.+ )$ - id: check-json + exclude: | + (?x)^( + .vscode/settings_recommended.json + )$ - id: check-yaml exclude: | (?x)^( diff --git a/.vscode/settings_recommended.json b/.vscode/settings_recommended.json new file mode 100644 index 00000000000..3e038138486 --- /dev/null +++ b/.vscode/settings_recommended.json @@ -0,0 +1,25 @@ +{ + + // ========== Anylysis ========== + // It is a placeholder to let you know that we can include the extra paths for the better analysis(like go to definition of an extra package). + "python.analysis.extraPaths":[ + ], + + // ========== Type Hints ========== + // Use Pylance for insert tpype hints automatically + // Rrequired Plugins: + // - Python, https://marketplace.visualstudio.com/items?itemName=ms-python.python + // - Pylance, https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance + "python.languageServer": "Default", + "python.analysis.inlayHints.callArgumentNames": "off", + "python.analysis.inlayHints.functionReturnTypes": true, + "python.analysis.inlayHints.pytestParameters": true, + "python.analysis.inlayHints.variableTypes": true, + + // ========== Better comments ========== + // Rrequired Plugins: + // - Better Comments, https://marketplace.visualstudio.com/items?itemName=aaron-bond.better-comments + // It is a placeholder to let you know that we can use Better Comments plugin. We use the default settings. + "better-comments.highlightPlainText": false, + +} diff --git a/docs/source/CONTRIBUTING.md b/docs/source/CONTRIBUTING.md index 317846f6b5b..58c703a20cd 100644 --- a/docs/source/CONTRIBUTING.md +++ b/docs/source/CONTRIBUTING.md @@ -2,7 +2,7 @@ Contribution Guidelines ======================= 1. [Create Pull Request](#create-pull-request) 2. [Pull Request Checklist](#pull-request-checklist) -3. [Pull Request Template](#distillation-support-matrix) +3. [Pull Request Template](#pull-request-template) 4. [Pull Request Acceptance Criteria](#pull-request-acceptance-criteria) 5. [Pull Request Status Checks Overview](#pull-request-status-checks-overview) 6. [Support](#support) @@ -10,23 +10,23 @@ Contribution Guidelines ## Create Pull Request If you have improvements to Intel® Neural Compressor, send your pull requests for -[review](https://github.com/intel/neural-compressor/pulls). -If you are new to GitHub, view the pull request [How To](https://help.github.com/articles/using-pull-requests/). +[review](https://github.com/intel/neural-compressor/pulls). +If you are new to GitHub, view the pull request [How To](https://help.github.com/articles/using-pull-requests/). ### Step-by-Step guidelines -- Star this repository using the button `Star` in the top right corner. +- Star this repository using the button `Star` in the top right corner. - Fork this Repository using the button `Fork` in the top right corner. -- Clone your forked repository to your pc. +- Clone your forked repository to your pc. `git clone "url to your repo"` -- Create a new branch for your modifications. -`git checkout -b new-branch` -- Add your files with `git add -A`, commit `git commit -s -m "This is my commit message"` and push `git push origin new-branch`. +- Create a new branch for your modifications. +`git checkout -b new-branch` +- Add your files with `git add -A`, commit `git commit -s -m "This is my commit message"` and push `git push origin new-branch`. - Create a [pull request](https://github.com/intel/neural-compressor/pulls). ## Pull Request Checklist Before sending your pull requests, follow the information below: -- Changes are consistent with the Python [Coding Style](https://github.com/google/styleguide/blob/gh-pages/pyguide.md). +- Changes are consistent with the [coding conventions](./coding_style.md). - Add unit tests in [Unit Tests](https://github.com/intel/neural-compressor/tree/master/test) to cover the code you would like to contribute. - Intel® Neural Compressor has adopted the [Developer Certificate of Origin](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin), you must agree to the terms of Developer Certificate of Origin by signing off each of your commits with `-s`, e.g. `git commit -s -m 'This is my commit message'`. diff --git a/docs/source/coding_style.md b/docs/source/coding_style.md new file mode 100644 index 00000000000..a7e43da97d7 --- /dev/null +++ b/docs/source/coding_style.md @@ -0,0 +1,243 @@ +# INC Coding Conventions + + (Mostly for Version 3 and later) + +## Background + +To improve the quality and maintainability of INC code, we summarized some common coding standards and conventions. + +There are many style guides, and they may conflict with each other. To avoid overly arguing formatting, we make decisions based on the following priorities: + +- [Google Python Style](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings), [PEP 8](https://peps.python.org/pep-0008/) +- Framework Style +- INC Internal Style +- Sub-module specific Style + +## Rules + +> Note: The sub-tile naming is following [Google Python Style](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings) and [PEP 8](https://peps.python.org/pep-0008/). See the relevant section for more details. + + +### Imports + +- Recommend + +```python +import os +import sys + +from x import py +from x import y as z +from copy import deepcopy +from subprocess import Popen, PIPE +``` + +- Not recommend + +```python +from sub_module import * # May lead to namespace pollution +import os, sys # Import on separate lines +import copy # May import local copy.py +``` + +### Strings + +- Recommend + +```python +long_string = """This is fine if your use case can accept + extraneous leading spaces.""" + +long_string = "And this is fine if you cannot accept\n" "extraneous leading spaces." +``` + +- Not recommend + +```python +logger.info("This is fine if your use case can accept") +logger.info("extraneous leading spaces.") +``` + +### Logger + +- Recommend + +```python +from neural_compressor.common import logger + +logger.info("Current TensorFlow Version is: %s", tf.__version__) # Use a pattern-string (with %-placeholders) + +logger.info("Current $PAGER is: %s", os.getenv("PAGER", default="")) # Better readability + +# Handle long string +logger.warning( + "All tuning options for the current strategy have been tried. \n" + "If the quantized model does not seem to work well, it might be worth considering other strategies." +) + +logger.warning( + "This is a long string, this is a long string," + "override the user config's smooth quant alpha into the best alpha(%.4f) found in pre-strategy.", + 0.65421, +) +``` + +- Not recommend + +```python +logger.info(f"Current TensorFlow Version is: {tf.__version__}") # Use f-string + +logger.info("Current $PAGER is:") # One sentence in two lines +logger.info(os.getenv("PAGER", default="")) +``` + + +### Type Annotations + +- Recommend + +```python +def register_config(framework_name: str, algo_name: str, priority: int = 0) -> Callable[..., Any]: ... + + +eval_result: float = evaluator.eval(model) + +# Declare aliases of complex types +from typing import TypeAlias + +_LossAndGradient: TypeAlias = tuple[tf.Tensor, tf.Tensor] +ComplexTFMap: TypeAlias = Mapping[str, _LossAndGradient] +``` + +- Not recommend + +```python +def xx_func(cls) -> Dict[str, OrderedDict[str, Dict[str, object]]]: # Can't improve the readability +``` + +- Plugs: + - [python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) + - [pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) + + +### Comments + +- Recommend + +```python +class CheeseShopAddress: + """The address of a cheese shop. + + ... + """ + + +class OutOfCheeseError(Exception): + """No more cheese is available.""" +``` + +- Not recommend + +```python +class CheeseShopAddress: + """Class that describes the address of a cheese shop. + + ... + """ + + +class OutOfCheeseError(Exception): + """Raised when no more cheese is available.""" +``` + + +### TODO Comments + +- Recommend + +```python +# TODO: crbug.com/192795 - Investigate cpufreq optimizations. + +# * Important information +# ? Need decision +# ! Deprecated method, do not use +``` + +> A `TODO` comment begins with the word `TODO:` for facilitate searching. + +- Plug: + [Better Comments](https://marketplace.visualstudio.com/items?itemName=aaron-bond.better-comments) + + +### Public and Internal Interfaces + +Use `__all__` to help the developer and user know the supported interface and components. + +```python +__all__ = [ + "options", + "register_config", + "get_all_config_set_from_config_registry", + "BaseConfig", + "ComposableConfig", +] +``` + + +## Folder structure + +```shell +├── fwk_name +│ ├── __init__.py +│ ├── quantization +│ │ ├── algorithm_entry.py +│ │ ├── autotune.py +│ │ ├── config.py +│ │ ├── __init__.py +│ │ └── quantize.py +│ ├── algorithms +│ │ ├── __init__.py +│ │ ├── smooth_quant +│ │ │ ├── __init__.py +│ │ │ ├── smooth_quant.py +│ │ │ └── utility.py +│ │ ├── static_quant +│ │ │ ├── __init__.py +│ │ │ ├── static_quant.py +│ │ │ └── utility.py +│ │ └── weight_only +│ │ ├── gptq.py +│ │ ├── __init__.py +│ │ └── rtn.py +│ └── utils +│ ├── constants.py +│ ├── __init__.py +│ └── utility.py +└── __init__.py +``` + +```python +# * Note: some code snippets about register algorithm entry +# filepath: neural_compressor/fwk_name/quantization/algorithm_entry.py +@register_algo(RTN) +def rtn_algo_entry() + from neural_compressor.fwk_name.algorithms import rtn + ... + +@register_algo(SMOOTH_QUANT) +def smooth_quant_entry(): + from neural_compressor.fwk_name.algorithms import smooth_quant + ... + +``` + + +## Recommend VS Code `settings.json` +To keep the coding style consistent, we suggest you replace `.vscode/settings.json` with `neural-compressor/.vscode/settings_recommended.json`. + + +## Reference + +- [Google Python Style](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings) +- [PEP 8](https://peps.python.org/pep-0008/) +- [PyTorch](https://github.com/pytorch/pytorch)