Refine Copyright Documentation

codeformatting/Copyright-Headers.md

@@ -1,29 +1,37 @@
 
-# Copyright - Headers
+[ [SPDX Annotations][SPDX] ] [ [Snippets] ]
 
-The addition of copyright headers is currently required for newly added files if **ALL** of the following conditions apply:
+# Copyright : Headers
 
-1.  The file is `C++` or `Python` source code
+Copyright headers are an artifact of old software, they are currently still kept around for any existing files that have them and are added to new `C++` & `Python` source files.
 
-2.  The file is purely original code
+<br/>
+
+## Conditions
+
+Copyright headers should be added to new files if **ALL** of the following apply:
 
-3.  The code was written for the FreeCAD project
+1.  The file is `C++` or `Python` source code.
 
-4.  The code is licensed under `LGPL-2.1-or-later`
+2.  The file is purely original code.
+
+3.  The code was written for the FreeCAD project.
+
+4.  The code is licensed under `LGPL-2.1-or-later`.
 
 <br/>
 
-## Declarations
+## Statements
 
 Copyright statements should be made via SPDX annotations.
 
-[» Read about SPDX in the FreeCAD project.](./Copyright-SPDX)
+[» How to add **SPDX Annotations**.][SPDX]
 
 <br/>
 
 ## License Text
 
-[» Find this header in language you need.](./Copyright-Snippets)
+[» Find this header in the language you need.][Snippets]
 
 ```
 FreeCAD is free software: you can redistribute it and/or modify
@@ -41,3 +49,6 @@ License along with FreeCAD. If not, see https://www.gnu.org/licenses
 ```
 
 <br/>
+
+[Snippets]: ./Copyright-Snippets
+[SPDX]: ./Copyright-SPDX

codeformatting/Copyright-SPDX.md

@@ -1,15 +1,35 @@
 
-# Copyright - SPDX
+[ [Copyright Headers][Headers] ] [ [Snippets] ]
 
-SPDX is used to declare metadata about a file, like what license its published under or who owns the copyright. The annotations are usually placed within inline comments at the start of the file.
+# Copyright : SPDX
 
-*In cases where the first line of a file is already occupied by for example a shebang declaration `#!/usr/bin/env bash`, simply place the SPDX annotations on the next lines after.*
+
+SPDX annotations declare metadata about the file they are placed in, like the license of the content contained within, the copyright holders or where the content originates from.
+
+Generally every file whose format allows adding comments should contain SPDX annotations.
+
+<br/>
+
+## Placement
+
+SPDX annotations should be placed in inline comments at the top of the file.
+
+```C++
+// SPDX-License-Identifier: LGPL-2.1-or-later
+```
+
+Some file formats or file content may prevent this, for example shebang declarations may already occupy the first line in a script file, in that case simply add the annotations in the following lines.
+
+```sh
+#!/usr/bin/env bash
+# SPDX-License-Identifier: LGPL-2.1-or-later
+```
 
 <br/>
 
 ## License
 
-To declare what license a file falls under, specify the appropriate [License Id] in the following format:
+To declare what license a file falls under, specify the appropriate [License Id] in the following way:
 
 ```
 SPDX-License-Identifier: ‹License Id›
@@ -31,7 +51,7 @@ SPDX-License-Identifier: ‹License Id›
 
 ## Copyright
 
-To declare who own the copyright to a file, declare one annotation for every person / organization.
+To declare who holds the copyright to a file, add one annotation for every person / organization:
 
 ```
 SPDX-FileCopyrightText: ‹Year› ‹Entity›
@@ -131,3 +151,5 @@ Besides the wiki, currently we don't license documentation, however you might wa
 
 
 [License Id]: https://spdx.org/licenses/
+[Snippets]: ./Copyright-Snippets
+[Headers]: ./Copyright-Headers

codeformatting/Copyright-Snippets.md

@@ -1,11 +1,9 @@
 
-# Copyright - Snippets
+[ [SPDX Annotations][SPDX] ] [ [Copyright Headers][Headers] ] [ [Licenses] ]
 
-The following are snippets for various language for your convenience.
+# Copyright : Snippets
 
-[» Read how copyright is handled in the FreeCAD Project.][License Identifier]
-
-[» List of SPDX License Identifiers][License Identifier]
+Below you will find some snippets of the commonly used SPDX annotations / copyright headers.
 
 <br/>
 
@@ -65,7 +63,7 @@ The following are snippets for various language for your convenience.
 
 ## Other
 
-*Reminder other file types only need SPDX annotations.*
+*Reminder: Other file types only require SPDX annotations, not copyright headers.*
 
 
 ```C++
@@ -100,5 +98,6 @@ The following are snippets for various language for your convenience.
 
 <br/>
 
-[License Identifier]: https://spdx.org/licenses/
-[Copyright]: ./Copyright.md
+[Licenses]: https://spdx.org/licenses/
+[Headers]: ./Copyright-Headers
+[SPDX]: ./Copyright-SPDX

codeformatting/index.md

@@ -10,15 +10,15 @@ FreeCAD is written primarily in C++ and Python (with a few files in other langua
 
 ## Copyright
 
-When creating new files in the FreeCAD project, you should - if the file format allows - add the appropriate SPDX annotation.
+Every file in the FreeCAD project should contain [SPDX Annotations][Copyright-SPDX] if possible.
 
-In source files like Python & C++ it is also required to add a copyright header.
+C++ and Python source files are currently also required to have [Copyright Headers][Copyright-Headers].
 
-[» How to add SPDX annotations](./Copyright-SPDX)
+[» How to add **SPDX Annotations**.][Copyright-SPDX]
 
-[» How to add Copyright Headers](./Copyright-Headers)
+[» How to add **Copyright Headers**.][Copyright-Headers]
 
-[» Snippets for your convenience](./Copyright-Snippets)
+[» **Snippets** for your convenience.][Copyright-Snippets]
 
 ## Setting up pre-commit
 
@@ -41,3 +41,8 @@ There is no unified Python coding style agreed upon for the FreeCAD codebase: ea
 ## Inline documentation
 
 You will find a mix of different generations of comment-based inline documentation systems in the code base depending on when the code was written.  As of 2024 it is preferred that you write [doxygen](https://www.doxygen.nl/manual/docblocks.html) compatible comment documentation.  For methods, including the @param and @return as appropriate is highly recommended.
+
+
+[Copyright-Snippets]: ./Copyright-Snippets
+[Copyright-Headers]: ./Copyright-Headers
+[Copyright-SPDX]: ./Copyright-SPDX

technical/codesigning.md

@@ -120,7 +120,7 @@ If you would like to configure a build of FreeCAD to sign with your own certific
 9. From the Artifact Signing Account's page, choose the Access Control settings from the left sidebar, add a role assignment, and search for "Artifact Signing Certificate Profile Signer". Select that role, click Next (hiding at the bottom of the screen), and assign that role to your account.
 10. Log out of your current scope, and into the code-signing scope using the tenant ID found in the portal at Microsoft Entra ID → Overview → Tenant ID
     ```
-    az login --tenant YOUR_TENANT_ID --use-device-code --scope "https://codesigning.azure.net/.default" 
+    az login --tenant YOUR_TENANT_ID --use-device-code --scope "https://codesigning.azure.net/.default"
     ```
     Follow the prompts to log in using your browser.