diff --git a/docs/en/contribute/copyright-guide.rst b/docs/en/contribute/copyright-guide.rst index 3738717632..0dc929fc50 100644 --- a/docs/en/contribute/copyright-guide.rst +++ b/docs/en/contribute/copyright-guide.rst @@ -1,18 +1,20 @@ Copyright Header Guide ====================== +:link_to_translation:`zh_CN:[中文]` + .. highlight:: c ESP-IDF is released under :project_file:`the Apache License 2.0 ` with some additional third-party copyrighted code released under various licenses. For further information please refer to :doc:`the list of copyrights and licenses <../../../COPYRIGHT>`. -This page explains how the source code should be properly marked with a copyright header. ESP-IDF uses `The Software Package Data Exchange (SPDX) `_ format which is short and can be easily read by humans or processed by automated tools for copyright checks. +This page explains how the source code should be properly marked with a copyright header. ESP-IDF uses the `Software Package Data Exchange (SPDX) `_ format which is short and can be easily read by humans or processed by automated tools for copyright checks. How to Check the Copyright Headers ---------------------------------- -Please make sure you have installed :doc:`the pre-commit hooks ` which contain a copyright header checker as well. The checker can suggest a header if it is not able to detect a properly formatted SPDX header. +Please make sure you have installed the :doc:`pre-commit hooks ` which contain a copyright header checker as well. The checker can suggest a header if it is not able to detect a properly formatted SPDX header. -What if the Checker's Suggestion is Incorrect? +What If the Checker's Suggestion Is Incorrect? ---------------------------------------------- No automated checker (no matter how good is) can replace humans. So the developer's responsibility is to modify the offered header to be in line with the law and the license restrictions of the original code on which the work is based on. Certain licenses are not compatible between each other. Such corner cases will be covered by the following examples. @@ -30,7 +32,7 @@ The simplest case is when the code is not based on any licensed previous work, e * SPDX-License-Identifier: Apache-2.0 */ -Less restrictive parts of ESP-IDF +Less Restrictive Parts of ESP-IDF ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Some parts of ESP-IDF are deliberately under less restrictive licenses in order to ease their re-use in commercial closed source projects. This is the case for :project:`ESP-IDF examples ` which are in Public domain or under the Creative Commons Zero Universal (CC0) license. The following header can be used in such source files:: @@ -43,7 +45,7 @@ Some parts of ESP-IDF are deliberately under less restrictive licenses in order The option allowing multiple licenses joined with the ``OR`` keyword from the above example can be achieved with the definition of multiple allowed licenses in the ``tools/ci/check_copyright_config.yaml`` configuration file. Please use this option with care and only selectively for a limited part of ESP-IDF. -Third party licenses +Third Party Licenses ~~~~~~~~~~~~~~~~~~~~ Code licensed under different licenses, modified by Espressif Systems and included in ESP-IDF cannot be licensed under Apache License 2.0 not even if the checker suggests it. It is advised to keep the original copyright header and add an SPDX before it. diff --git a/docs/en/contribute/install-pre-commit-hook.rst b/docs/en/contribute/install-pre-commit-hook.rst index 196bfcce35..234641de41 100644 --- a/docs/en/contribute/install-pre-commit-hook.rst +++ b/docs/en/contribute/install-pre-commit-hook.rst @@ -1,29 +1,31 @@ Install pre-commit Hook for ESP-IDF Project =========================================== +:link_to_translation:`zh_CN:[中文]` + Required Dependency ------------------- -Python 3.7.* or above. This is our recommended python version for IDF developers. +Python 3.7.* or above. This is our recommended Python version for IDF developers. -If you still have python versions not compatible, update your python versions before installing the pre-commit hook. +If you still have Python versions not compatible, update your Python versions before installing the pre-commit hook. Install pre-commit ------------------ Run ``pip install pre-commit`` -Install pre-commit hook +Install pre-commit Hook ----------------------- -1. Go to the IDF Project Directory +1. Go to the IDF project directory. 2. Run ``pre-commit install --allow-missing-config -t pre-commit -t commit-msg``. Install hook by this approach will let you commit successfully even in branches without the ``.pre-commit-config.yaml`` 3. pre-commit hook will run automatically when you're running ``git commit`` command -Uninstall pre-commit --------------------- +Uninstall pre-commit Hook +----------------------------- Run ``pre-commit uninstall`` @@ -39,14 +41,14 @@ Common Problems For Windows Users ``/usr/bin/env: python: Permission denied.`` - If you're in Git Bash, please check the python executable location by run ``which python``. + If you're in Git Bash, please check the Python executable location by run ``which python``. If the executable is under ``~/AppData/Local/Microsoft/WindowsApps/``, then it's a link to Windows AppStore, not a real one. - Please install python manually and update this in your ``PATH`` environment variable. + Please install Python manually and update this in your ``PATH`` environment variable. -Your %USERPROFILE% contains non-ASCII characters +Your ``USERPROFILE`` contains non-ASCII characters ``pre-commit`` may fail when initializing an environment for a particular hook when the path of ``pre-commit``'s cache contains non-ASCII characters. The solution is to set ``PRE_COMMIT_HOME`` to a path containing only standard characters before running pre-commit. diff --git a/docs/zh_CN/contribute/copyright-guide.rst b/docs/zh_CN/contribute/copyright-guide.rst index 700b25a9d1..9a879d9b64 100644 --- a/docs/zh_CN/contribute/copyright-guide.rst +++ b/docs/zh_CN/contribute/copyright-guide.rst @@ -1 +1,89 @@ -.. include:: ../../en/contribute/copyright-guide.rst +版权标头指南 +========================= + +:link_to_translation:`en:[English]` + +.. highlight:: c + +ESP-IDF 基于 Apache License 2.0，并包含一些不同许可证下的第三方版权代码。要了解更多信息，请参考 :doc:`the list of copyrights and licenses <../../../COPYRIGHT>`。 + +本页面介绍了如何在源代码中正确标注版权标头。ESP-IDF 使用 `Software Package Data Exchange (SPDX) `_ 格式，简短易读，能够方便自动化工具处理及进行版权检查。 + +如何检查版权标头 +--------------------------- + +请确保你已安装了包含版权标头检查器的 :doc:`pre-commit hooks `。若该检查器无法检测到格式正确的 SPDX 标头，则会提供标头建议。 + +检查器的建议不正确怎么办 +--------------------------------- + +再好的自动化检查工具都无法取代人工检查。因此，开发者有责任修改检查器提供的标头，使其符合源代码的法律规范和许可证要求。某些许可证可能并不兼容，请参考后文示例。 + +检查器由 ``tools/ci/check_copyright_config.yaml`` 进行配置。请检查该配置文件提供的选项，并根据实际情况进行更新，以正确匹配标头。 + +常见版权标头示例 +-------------------------- + +最简单的情况是，你的代码不基于任何此前已获得许可的代码，例如你完全独立完成的代码。此类代码可以使用如下版权标头，并放在 ESP-IDF 许可证下:: + + /* + * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: Apache-2.0 + */ + +ESP-IDF 限制性较小的部分 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ESP-IDF 的某些部分特意采用了限制性较小的许可证，方便在商业闭源代码项目中重复使用。例如公有域下或免费知识共享 (CC0) 许可下的 :project:`ESP-IDF examples `。此类源文件可使用如下标头:: + + /* + * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: Unlicense OR CC0-1.0 + */ + +如允许使用多个许可证，可采用关键字 ``OR`` 连接，如上例所示。这可以通过在 ``tools/ci/check_copyright_config.yaml`` 配置文件中定义多个许可证实现。但是，请谨慎使用该方法，并仅在 ESP-IDF 项目限制性较小的部分中选择性使用。 + +第三方许可证 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +受到不同许可证许可，经 Espressif Systems 修改，并包含在 ESP-IDF 中的代码不能使用 Apache License 2.0 进行许可，即便检查器可能提出此类建议。建议保留原有版权标头，并在前面添加 SPDX 标识。 + +例如，对于一个由 "GNU General Public License v2.0 及以上" 许可证许可、John Doe 持有、且由 Espressif Systems 做出额外修改的代码文件，请按照如下示例提供标头:: + + /* + * SPDX-FileCopyrightText: 1991 John Doe + * + * SPDX-License-Identifier: GPL-2.0-or-later + * + * SPDX-FileContributor: 2019-2023 Espressif Systems (Shanghai) CO LTD + */ + +这些许可证能够得到识别，并且可以在官方 `SPDX license list`_ 中找到 SPDX 标识符。其他常见许可证还包括 GPL-2.0-only，BSD-3-Clause 和 BSD-2-Clause。 + +特殊情况下， 如果一个许可证没有包含在 `SPDX license list`_ 中，可使用 `LicenseRef-[idString]`_ 自定义许可证标识符，如以下示例中的 ``LicenseRef-Special-License``。另外，必须把完整的许可文本添加到 ``Special-License`` 文件夹下的 ``LICENSES`` 路径中:: + + /* + * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: LicenseRef-Special-License + */ + +如果自定义许可证直接包含在源文件中，可使用专门的自定义许可证标识符 ``LicenseRef-Included`` 进行说明:: + + /* + * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: LicenseRef-Included + * + * + */ + +``tools/ci/check_copyright_config.yaml`` 中的配置为第三方许可证提供了许多有用的功能： + +* 对第三方程序库的文件部分，可以定义一个不同的许可证。 +* 可以永久禁用对选定文件集的检查。请谨慎使用该选项，并且仅在其他选项都不适用时，才可使用该选项。 + +.. _SPDX license list: https://spdx.org/licenses +.. _LicenseRef-[idString]: https://spdx.github.io/spdx-spec/v2.3/other-licensing-information-detected/#101-license-identifier-field \ No newline at end of file diff --git a/docs/zh_CN/contribute/install-pre-commit-hook.rst b/docs/zh_CN/contribute/install-pre-commit-hook.rst index 7a6b2ba9f7..5ebfc652ec 100644 --- a/docs/zh_CN/contribute/install-pre-commit-hook.rst +++ b/docs/zh_CN/contribute/install-pre-commit-hook.rst @@ -1 +1,57 @@ -.. include:: ../../en/contribute/install-pre-commit-hook.rst +为 ESP-IDF 安装 pre-commit 钩子 +========================================== + +:link_to_translation:`en:[English]` + +环境依赖 +--------------- + +我们向 IDF 开发人员推荐 Python 3.7.* 及以上版本。 + +如果你已安装了不兼容的 Python 版本，应在安装 pre-commit 工具前进行更新。 + +安装 pre-commit 工具 +--------------------------- + +运行 ``pip install pre-commit`` 。 + +安装 pre-commit 钩子 +---------------------------- + +1. 切换到 IDF 项目路径。 + +2. 运行 ``pre-commit install --allow-missing-config -t pre-commit -t commit-msg`` 命令。 使用这种方式安装钩子后，即使在没有 ``.pre-commit-config.yaml`` 的分支中也能成功提交。 + +3. 在运行 ``git commit`` 命令时，pre-commit 钩子会自动运行。 + +卸载 pre-commit 钩子 +---------------------- + +运行 ``pre-commit uninstall`` 。 + +更多 +--------- + +更多详细使用方法，请参考 pre-commit_ 文档。 + +.. _pre-commit: https://pre-commit.com/ + +Windows 用户常见问题 +-------------------------------- + +``/usr/bin/env: python: Permission denied.`` + + 如果使用 Git Bash，请运行 ``which python`` 检查 Python 的可执行位置。 + + 如果该可执行文件位于 ``~/AppData/Local/Microsoft/WindowsApps/``，这其实是一个到 Windows 应用商店的链接，而不是真正的可执行文件。 + + 请手动安装 Python，并在 ``PATH`` 环境变量中进行更新。 + + +你的 ``USERPROFILE`` 中包含非 ASCII 字符 + + 如果 ``pre-commit`` 的缓存路径包含非 ASCII 字符， 用 ``pre-commit`` 为特定钩子初始化环境时可能会失败。解决方案是，将 ``PRE_COMMIT_HOME`` 设置为一个仅包含标准字符的路径，然后再运行 pre-commit。 + + - CMD: ``set PRE_COMMIT_HOME=C:\somepath\pre-commit`` + - PowerShell: ``$Env:PRE_COMMIT_HOME = "C:\somepath\pre-commit"`` + - git bash: ``export PRE_COMMIT_HOME="/c/somepath/pre-commit"``