From 4d149f070cdf4058982172f0ccf6faa92a7e9ec5 Mon Sep 17 00:00:00 2001 From: Roland Dobai Date: Tue, 2 Nov 2021 16:31:51 +0100 Subject: [PATCH] Docs: Add copyright header guide for contributions --- CONTRIBUTING.rst | 3 +- docs/en/contribute/copyright-guide.rst | 55 +++++++++++++++++++++++ docs/zh_CN/contribute/copyright-guide.rst | 1 + 3 files changed, 58 insertions(+), 1 deletion(-) create mode 100644 docs/en/contribute/copyright-guide.rst create mode 100644 docs/zh_CN/contribute/copyright-guide.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 0c506acf4f..0025a9ef0b 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -13,7 +13,7 @@ Before Contributing Before sending us a Pull Request, please consider this list of points: -* Is the contribution entirely your own work, or already licensed under an Apache License 2.0 compatible Open Source License? If not then we unfortunately cannot accept it. +* Is the contribution entirely your own work, or already licensed under an Apache License 2.0 compatible Open Source License? If not then we unfortunately cannot accept it. Please check the :doc:`Copyright Header Guide ` for additional information. * Does any new code conform to the esp-idf :doc:`Style Guide `? @@ -59,3 +59,4 @@ Related Documents creating-examples ../api-reference/template contributor-agreement + copyright-guide diff --git a/docs/en/contribute/copyright-guide.rst b/docs/en/contribute/copyright-guide.rst new file mode 100644 index 0000000000..3c68bdae94 --- /dev/null +++ b/docs/en/contribute/copyright-guide.rst @@ -0,0 +1,55 @@ +Copyright Header Guide +====================== + +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. + +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. + +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. + +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-2021 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 ` 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-2021 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: Unlicense OR CC0-1.0 + */ + +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-2021 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. diff --git a/docs/zh_CN/contribute/copyright-guide.rst b/docs/zh_CN/contribute/copyright-guide.rst new file mode 100644 index 0000000000..700b25a9d1 --- /dev/null +++ b/docs/zh_CN/contribute/copyright-guide.rst @@ -0,0 +1 @@ +.. include:: ../../en/contribute/copyright-guide.rst