From da2029e6fc61ff049f1270eb49f949bb3a73899c Mon Sep 17 00:00:00 2001 From: PhoneDroid <73050054+PhoneDroid@users.noreply.github.com> Date: Fri, 6 Mar 2026 11:30:10 -0500 Subject: [PATCH 1/2] Refine Copyright Documentation --- codeformatting/Copyright-Headers.md | 29 +++++++++++++++++-------- codeformatting/Copyright-SPDX.md | 32 +++++++++++++++++++++++----- codeformatting/Copyright-Snippets.md | 15 ++++++------- codeformatting/index.md | 15 ++++++++----- 4 files changed, 64 insertions(+), 27 deletions(-) diff --git a/codeformatting/Copyright-Headers.md b/codeformatting/Copyright-Headers.md index 3fcc8ac..fd1bc27 100644 --- a/codeformatting/Copyright-Headers.md +++ b/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 +
+ +## 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`.
-## 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]
## 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 ```
+ +[Snippets]: ./Copyright-Snippets +[SPDX]: ./Copyright-SPDX \ No newline at end of file diff --git a/codeformatting/Copyright-SPDX.md b/codeformatting/Copyright-SPDX.md index 855185f..f100220 100644 --- a/codeformatting/Copyright-SPDX.md +++ b/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. + +
+ +## 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 +```
## 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 diff --git a/codeformatting/Copyright-Snippets.md b/codeformatting/Copyright-Snippets.md index dc8fd84..0b44664 100644 --- a/codeformatting/Copyright-Snippets.md +++ b/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.
@@ -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.
-[License Identifier]: https://spdx.org/licenses/ -[Copyright]: ./Copyright.md \ No newline at end of file +[Licenses]: https://spdx.org/licenses/ +[Headers]: ./Copyright-Headers +[SPDX]: ./Copyright-SPDX \ No newline at end of file diff --git a/codeformatting/index.md b/codeformatting/index.md index eb542ba..e3c5540 100644 --- a/codeformatting/index.md +++ b/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 \ No newline at end of file From 9ab90734869e83b83527031f1f07984bd13a9c50 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 6 Mar 2026 16:31:39 +0000 Subject: [PATCH 2/2] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- codeformatting/Copyright-Headers.md | 2 +- codeformatting/index.md | 2 +- technical/codesigning.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/codeformatting/Copyright-Headers.md b/codeformatting/Copyright-Headers.md index fd1bc27..00b88d2 100644 --- a/codeformatting/Copyright-Headers.md +++ b/codeformatting/Copyright-Headers.md @@ -51,4 +51,4 @@ License along with FreeCAD. If not, see https://www.gnu.org/licenses
[Snippets]: ./Copyright-Snippets -[SPDX]: ./Copyright-SPDX \ No newline at end of file +[SPDX]: ./Copyright-SPDX diff --git a/codeformatting/index.md b/codeformatting/index.md index e3c5540..88bcc5b 100644 --- a/codeformatting/index.md +++ b/codeformatting/index.md @@ -45,4 +45,4 @@ You will find a mix of different generations of comment-based inline documentati [Copyright-Snippets]: ./Copyright-Snippets [Copyright-Headers]: ./Copyright-Headers -[Copyright-SPDX]: ./Copyright-SPDX \ No newline at end of file +[Copyright-SPDX]: ./Copyright-SPDX diff --git a/technical/codesigning.md b/technical/codesigning.md index 68a8a0a..708bbd4 100644 --- a/technical/codesigning.md +++ b/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.