mirror of
https://github.com/espressif/esp-idf.git
synced 2025-08-07 20:00:53 +00:00
Merge branch 'docs_add_CN_translation_for_cotribute/copyright-guide.rst_and_install-pre-commit-book.rst' into 'master'
docs: Provide CN translation for contribute/copyright-guide.rst and install-pre-commit-hook.rst Closes DOC-5883 and DOC-5884 See merge request espressif/esp-idf!25100
This commit is contained in:
@@ -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 <LICENSE>` 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) <https://spdx.dev>`_ 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) <https://spdx.dev>`_ 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 <install-pre-commit-hook>` 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 <install-pre-commit-hook>` 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 <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.
|
||||
|
@@ -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.
|
||||
|
||||
|
Reference in New Issue
Block a user