Add license info guidance to docs
Extends the Contributing page to provide more guidance on adding
and updating license and copyright information. Added link to
coding style page where some example license and copyright comment
blocks have been added.
Signed-off-by: Julian Hall <julian.hall@arm.com>
Change-Id: I139f1300420d32c04686ddf1dbf450fa5a7484e8
diff --git a/docs/project/coding-guidelines.rst b/docs/project/coding-guidelines.rst
index 3090aa4..ca80f1b 100644
--- a/docs/project/coding-guidelines.rst
+++ b/docs/project/coding-guidelines.rst
@@ -1,26 +1,23 @@
Coding Style & Guidelines
=========================
-The following sections contain |TS| coding guidelines. They are continually evolving and should not be considered "set
-in stone". Feel free to question them and provide feedback.
-
-The |TS| project uses multiple "domains" (textual content types, like programming languages) and each defines its own
-rules.
+The following sections contain |TS| coding guidelines for different types of file. They are continually evolving
+and should not be considered "set in stone". Feel free to question them and provide feedback.
To help configuring text editors the project comes with "`EditorConfig`_" file(s). (:download:`../../.editorconfig`).
-Shared rules
+Common Rules
------------
-The following rules are common for all domains, except where noted otherwise:
+The following rules are common for all types of text file, except where noted otherwise:
#. Files shall be **UTF-8** encoded.
#. Use **Unix** style line endings (``LF`` character)
#. The primary language of the project is English. All comments and documentation must be in this language.
#. Trailing whitespace is not welcome, please trim these.
-C Domain
---------
+C Rules
+-------
C source code rules are base on the *Linux Coding Style* (See: |LCS|). The following deviations apply:
@@ -33,13 +30,23 @@
alphabetically in the above two groups.
#. All variables must be initialized.
+C source files should include a copyright and license comment block at the head of each file. Here is an example::
+
+ /*
+ * Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
Boring stuff is not for smart people and the project uses the `Uncrustify`_ code beautifier to easy formatting the
source. (See :download:`../../.uncrustify.cfg`)
-CMake domain
-------------
+CMake Rules
+-----------
-11. CMake file names use `CamelCase`_ style.
+Cmake files (e.g. CMakeLists.txt and .cmake) should conform to the following rules:
+
+1. CMake file names use `CamelCase`_ style.
#. Indent with tabs and otherwise use spaces. Use 4 spaces for tab size.
#. Use LF as line end in CMake files.
#. Remove trailing whitespace.
@@ -53,10 +60,19 @@
#. Use the Sphinx CMake domain for in-line documentation of CMake scripts. For details please refer to the
`CMake Documentation`_.
+Each file should include a copyright and license comment block at the head of each file. Here is an example::
+
+ #-------------------------------------------------------------------------------
+ # Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved.
+ #
+ # SPDX-License-Identifier: BSD-3-Clause
+ #
+ #-------------------------------------------------------------------------------
+
.. todo:: Explain CMake return values and parent scope concept in more detail.
-Restructured Text Domain
-------------------------
+Restructured Text Rules
+-----------------------
Please refer to :doc:`/developer/writing-documentation`.
@@ -68,6 +84,6 @@
.. _`EditorConfig`: https://editorconfig.org/
.. _`Uncrustify`: https://github.com/uncrustify/uncrustify
-*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved.*
SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/project/contributing.rst b/docs/project/contributing.rst
index d9760d9..836502c 100644
--- a/docs/project/contributing.rst
+++ b/docs/project/contributing.rst
@@ -23,18 +23,18 @@
- Make sure your commit messages are in the proper format. Please keel the 50/72 rule (for details see `Tim Popes blog entry`_.)
- Where appropriate, please update the documentation.
- - Consider whether the this document or other in-source documentation
- needs updating.
+ - Consider which documents or other in-source documentation needs updating.
- Ensure that each changed file has the correct copyright and license information. Files that entirely consist of
contributions to this project should have a copyright notice and BSD-3-Clause SPDX license identifier of the form
- as shown in :ref:`license`. Files that contain changes to imported Third Party IP files should retain their
- original copyright and license notices. For significant contributions you may add your own copyright notice in
- following format::
+ as shown in :ref:`license`. Example copyright and license comment blocks are shown in :ref:`Coding Style & Guidelines`.
+ Files that contain changes to imported Third Party IP files should retain their original copyright and license
+ notices. For significant contributions you may add your own copyright notice in following format::
Portions copyright (c) [XXXX-]YYYY, <OWNER>. All rights reserved.
where XXXX is the year of first contribution (if different to YYYY) and YYYY is the year of most recent
contribution. *<OWNER>* is your name or your company name.
+ - For any change, ensure that YYYY is updated if a contribution is made in a year more recent than the previous YYYY.
- If you are submitting new files that you intend to be the technical sub-maintainer for (for example, a new platform
port), then also update the :ref:`maintainers` file.
- For topics with multiple commits, you should make all documentation changes (and nothing else) in the last commit
@@ -83,6 +83,6 @@
.. _`Tim Popes blog entry`: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
-*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved.*
SPDX-License-Identifier: BSD-3-Clause