mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
8e893db5f3
In a very rare cases there is a need to use custom license, which is not present on the SPDX list. Now, files under such license are added to the check_copyright ignore list. For example zigbee examples introduced by !16205. SPDX has a LicenseRef-[idstring] identifier[1] for such cases, so let's try to use it in license representation[2]. The idea is that licenses not on the SPDX list can be added into the LICENSES[3] directory and used as SPDX-License-Identifier: LicenseRef-Special-License Or if the custom license is present directly in a source file we can use a special LicenseRef-Included identifier to state that the license is included. SPDX-License-Identifier: LicenseRef-Included Please note that LicenseRef-Included is just a made up identifier to state the fact that the license is included directly in the source file. There is nothing in the SPDX spec about this usage. This relatively small adjustment allows to refer to custom licenses without a need to skip check_copyright for them. [1] https://spdx.github.io/spdx-spec/v2.3/other-licensing-information-detected/#101-license-identifier-field [2] https://spdx.github.io/spdx-spec/v2.3/using-SPDX-short-identifiers-in-source-files/#e4-representing-multiple-licenses [3] https://reuse.software/spec/ Signed-off-by: Frantisek Hrbata <frantisek.hrbata@espressif.com>
88 lines
5.0 KiB
ReStructuredText
88 lines
5.0 KiB
ReStructuredText
Copyright Header Guide
|
|
======================
|
|
|
|
.. 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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
The checker can be configured with the ``tools/ci/check_copyright_config.yaml`` configuration file. Please check the options it offers and consider updating it in order to match the headers correctly.
|
|
|
|
Common Examples of Copyright Headers
|
|
------------------------------------
|
|
|
|
The simplest case is when the code is not based on any licensed previous work, e.g. it was written completely from scratch. Such code can be decorated with the following copyright header and put under the license of ESP-IDF::
|
|
|
|
/*
|
|
* SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
|
|
*
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
|
|
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::
|
|
|
|
/*
|
|
* SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
|
|
*
|
|
* SPDX-License-Identifier: Unlicense OR CC0-1.0
|
|
*/
|
|
|
|
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
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
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.
|
|
|
|
The following example is a suitable header for a code licensed under the "GNU General Public License v2.0 or later" held by John Doe with some additional modifications done by Espressif Systems::
|
|
|
|
/*
|
|
* SPDX-FileCopyrightText: 1991 John Doe
|
|
*
|
|
* SPDX-License-Identifier: GPL-2.0-or-later
|
|
*
|
|
* SPDX-FileContributor: 2019-2023 Espressif Systems (Shanghai) CO LTD
|
|
*/
|
|
|
|
The licenses can be identified and the short SPDX identifiers can be found in the official `SPDX license list`_. Other very common licenses are the GPL-2.0-only, the BSD-3-Clause, and the BSD-2-Clause.
|
|
|
|
In exceptional case, when a license is not present on the `SPDX license list`_, it can be expressed by using the `LicenseRef-[idString]`_ custom license identifier, for example ``LicenseRef-Special-License``. The full license text must be added into the ``LICENSES`` directory under ``Special-License`` filename. ::
|
|
|
|
/*
|
|
* SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
|
|
*
|
|
* SPDX-License-Identifier: LicenseRef-Special-License
|
|
*/
|
|
|
|
Dedicated ``LicenseRef-Included`` custom license identifier can be used to express a situation when the custom license is included directly in the source file. ::
|
|
|
|
/*
|
|
* SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
|
|
*
|
|
* SPDX-License-Identifier: LicenseRef-Included
|
|
*
|
|
* <Full custom license text>
|
|
*/
|
|
|
|
The configuration stored in ``tools/ci/check_copyright_config.yaml`` offers features useful for third party licenses:
|
|
|
|
* A different license can be defined for the files part of a third party library.
|
|
* The check for a selected set of files can be permanently disabled. Please use this option with care and only in cases when none of the other options are suitable.
|
|
|
|
.. _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
|