Skip to content

Commit 5a47f09

Browse files
PhoneDroidPhoneDroid
authored
Reworked / Created Copyright Documentation (#146)
1 parent 445ae79 commit 5a47f09

File tree

3 files changed

+274
-58
lines changed

3 files changed

+274
-58
lines changed

‎codeformatting/Copyright-Snippets.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
2+
# Copyright - Snippets
3+
4+
The following are snippets for copy-pasting if you have already read the [Copyright] documentation.
5+
6+
[» List of SPDX License Identifiers][License Identifier]
7+
8+
<br/>
9+
10+
## C++
11+
12+
```C++
13+
// SPDX-License-Identifier: LGPL-2.1-or-later
14+
// SPDX-FileNotice: Part of the FreeCAD project.
15+
16+
/******************************************************************************
17+
* *
18+
* © <Year> <Entity> *
19+
* *
20+
* FreeCAD is free software: you can redistribute it and/or modify *
21+
* it under the terms of the GNU Lesser General Public License as *
22+
* published by the Free Software Foundation, either version 2.1 *
23+
* of the License, or (at your option) any later version. *
24+
* *
25+
* FreeCAD is distributed in the hope that it will be useful, *
26+
* but WITHOUT ANY WARRANTY; without even the implied warranty *
27+
* of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. *
28+
* See the GNU Lesser General Public License for more details. *
29+
* *
30+
* You should have received a copy of the GNU Lesser General Public *
31+
* License along with FreeCAD. If not, see https://www.gnu.org/licenses *
32+
* *
33+
******************************************************************************/
34+
```
35+
36+
## Python
37+
38+
```Python
39+
# SPDX-License-Identifier: LGPL-2.1-or-later
40+
# SPDX-FileNotice: Part of the FreeCAD project.
41+
42+
################################################################################
43+
# #
44+
# © <YEAR> <Entity> #
45+
# #
46+
# FreeCAD is free software: you can redistribute it and/or modify #
47+
# it under the terms of the GNU Lesser General Public License as #
48+
# published by the Free Software Foundation, either version 2.1 #
49+
# of the License, or (at your option) any later version. #
50+
# #
51+
# FreeCAD is distributed in the hope that it will be useful, #
52+
# but WITHOUT ANY WARRANTY; without even the implied warranty #
53+
# of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. #
54+
# See the GNU Lesser General Public License for more details. #
55+
# #
56+
# You should have received a copy of the GNU Lesser General Public #
57+
# License along with FreeCAD. If not, see https://www.gnu.org/licenses #
58+
# #
59+
################################################################################
60+
```
61+
62+
## Other
63+
64+
*Reminder other file types only need SPDX.*
65+
66+
```C++
67+
// SPDX-License-Identifier: LGPL-2.1-or-later
68+
// SPDX-FileNotice: Part of the FreeCAD project.
69+
```
70+
71+
```Python
72+
# SPDX-License-Identifier: LGPL-2.1-or-later
73+
# SPDX-FileNotice: Part of the FreeCAD project.
74+
```
75+
76+
```
77+
/* SPDX-License-Identifier: LGPL-2.1-or-later */
78+
/* SPDX-FileNotice: Part of the FreeCAD project. */
79+
```
80+
81+
<br/>
82+
83+
[License Identifier]: https://spdx.org/licenses/
84+
[Copyright]: ./Copyright.md

‎codeformatting/Copyright.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
2+
# Copyright
3+
4+
When creating new files in the FreeCAD project, you should - if possible - declare an `SPDX License Identifier` with the appropriate license.
5+
6+
In source files it is currently also required to add a `Copyright Header`.
7+
8+
[» Copyright Snippets](./Copyright-Snippets)
9+
10+
<br/>
11+
12+
## SPDX License Identifiers
13+
14+
SPDX is a simple way of declaring what license something and is declared by adding a comment in the following format to a file:
15+
16+
```
17+
SPDX-License-Identifier: <License>
18+
```
19+
20+
1. It should be placed at the start of a file.
21+
22+
( Example exception, shebangs `#!` come first )
23+
24+
2. You should use the appropriate [License Identifier].
25+
26+
<br/>
27+
28+
### Examples
29+
30+
#### 1. Internal C++ Source File
31+
32+
You just wrote a new `.cpp` file from scratch and want to license it under the standard license FreeCAD uses ( `LGPL-2.1-or-later` )
33+
34+
```c++
35+
// SPDX-License-Identifier: LGPL-2.1-or-later
36+
// SPDX-FileNotice: Part of the FreeCAD project.
37+
38+
...
39+
```
40+
41+
<br/>
42+
43+
#### 2. External C++ Source File
44+
45+
You want to include some pre-existing code licensed under a compatible but different license to what FreeCAD uses by default.
46+
47+
```c++
48+
// SPDX-License-Identifier: MIT
49+
// SPDX-FileNotice: Part of the FreeCAD project.
50+
51+
...
52+
```
53+
54+
<br/>
55+
56+
#### 3. Mixed Python Licensing
57+
58+
You have some existing code licensed under one license but also want to add some code under a different license.
59+
60+
```Python
61+
# SPDX-License-Identifier: LGPL-2.1-or-later AND MIT
62+
# SPDX-FileNotice: Part of the FreeCAD project.
63+
64+
...
65+
```
66+
67+
<br/>
68+
69+
#### 4. Executable Python Script
70+
71+
You have a Python script that has a Shebang to specify how it can be run.
72+
73+
```Python
74+
#!/usr/bin/env python3
75+
# SPDX-License-Identifier: LGPL-2.1-or-later
76+
# SPDX-FileNotice: Part of the FreeCAD project.
77+
78+
...
79+
```
80+
81+
<br/>
82+
83+
#### 5. Icons
84+
85+
Icons should have whatever license the author intended, for example `CC-BY-SA-4.0`.
86+
87+
In `svg` files this is declared via metadata, not an SPDX comment.
88+
89+
<br/>
90+
91+
#### 6. Documentation
92+
93+
Besides the wiki, currently don't license documentation, however you might want to consider putting that under the `Unlicense` or `CC-BY-SA-4.0`.
94+
95+
<br/>
96+
97+
## Copyright Headers
98+
99+
Copyright headers are currently required to be added to files if **ALL** of the following conditions apply:
100+
101+
1. The file is `C++` or `Python` source code
102+
103+
2. The file is solely licensed under `LGPL-2.1-or-later`
104+
105+
3. The code has been written for FreeCAD
106+
107+
( Do not mark included libraries with this )
108+
109+
<br/>
110+
111+
### Declarations
112+
113+
To declare the copyright holders, simply follow this format:
114+
115+
`© <Year> <Entity>`
116+
117+
- `<Year>` is the current year / the year you created the code.
118+
119+
- `<Entity>` is either you - the person - or your organization.
120+
121+
#### Examples
122+
123+
##### Person
124+
125+
`© 1999 Robert Robertson`
126+
127+
##### Organization
128+
129+
`© 2000 Crazy CAD Technologies`
130+
131+
132+
<br/>
133+
134+
### Languages
135+
136+
### C++
137+
138+
```C++
139+
/******************************************************************************
140+
* *
141+
* © <Year> <Entity> *
142+
* *
143+
* FreeCAD is free software: you can redistribute it and/or modify *
144+
* it under the terms of the GNU Lesser General Public License as *
145+
* published by the Free Software Foundation, either version 2.1 *
146+
* of the License, or (at your option) any later version. *
147+
* *
148+
* FreeCAD is distributed in the hope that it will be useful, *
149+
* but WITHOUT ANY WARRANTY; without even the implied warranty *
150+
* of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. *
151+
* See the GNU Lesser General Public License for more details. *
152+
* *
153+
* You should have received a copy of the GNU Lesser General Public *
154+
* License along with FreeCAD. If not, see https://www.gnu.org/licenses *
155+
* *
156+
******************************************************************************/
157+
```
158+
159+
<br/>
160+
161+
### Python
162+
163+
```Python
164+
################################################################################
165+
# #
166+
# © <Year> <Entity> #
167+
# #
168+
# FreeCAD is free software: you can redistribute it and/or modify #
169+
# it under the terms of the GNU Lesser General Public License as #
170+
# published by the Free Software Foundation, either version 2.1 #
171+
# of the License, or (at your option) any later version. #
172+
# #
173+
# FreeCAD is distributed in the hope that it will be useful, #
174+
# but WITHOUT ANY WARRANTY; without even the implied warranty #
175+
# of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. #
176+
# See the GNU Lesser General Public License for more details. #
177+
# #
178+
# You should have received a copy of the GNU Lesser General Public #
179+
# License along with FreeCAD. If not, see https://www.gnu.org/licenses #
180+
# #
181+
################################################################################
182+
```
183+
184+
<br/>
185+
186+
[License Identifier]: https://spdx.org/licenses/

‎codeformatting/index.md‎

Lines changed: 4 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@ Guidelines for code formatting in C++ and Python
88

99
FreeCAD is written primarily in C++ and Python (with a few files in other languages such as CMake). To smooth the process of merging new contributions it is desirable to minimize formatting changes to existing code, and to use a uniform code formatting style when writing new code. Eventually we expect to standardize the codebase on specific coding styles using Clang Format for C++ and a Python code-formatter (such as Black), but that is a work-in-progress and _should not_ be applied to existing otherwise-untouched code.
1010

11+
## Copyright
12+
13+
[» Read more about SPDX & Copyright Headers](./Copyright)
14+
1115
## Setting up pre-commit
1216

1317
For the sections of the code that have already been auto-formatted, we use [git pre-commit hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) to enforce that formatting. We use the [pre-commit](https://pre-commit.com/) framework to install and manage our hooks. All developers should install pre-commit following the [instructions here](https://freecad.github.io/DevelopersHandbook/gettingstarted/). When making a new commit, the hooks examine your changed files and ensure that they follow the appropriate formatting for the section of code you are working on. You do not need to manually yourself with your code's formatting as you develop, and may code it as you like (or as your IDE likes...). The hook will ensure that your finished code conforms to project requirements.
@@ -20,68 +24,10 @@ Currently the following sections of code are covered by pre-commit: `src/Mod/Add
2024

2125
FreeCAD's codebase currently includes a [.clang-format](https://github.com/FreeCAD/FreeCAD/blob/master/.clang-format) file. Many IDEs will automatically apply these settings when editing files. To minimize disruption of other developers, only new or significantly-refactored code should have the formatting automatically applied. Code not being worked on should not be automatically formatted at this time.
2226

23-
### C++ Copyright Header
24-
25-
The following is the standard C++ copyright header that should be included in all new C++ files (and backported to files a developer is making significant changes to if they do not already have this format).
26-
27-
```cpp
28-
// SPDX-License-Identifier: LGPL-2.1-or-later
29-
/****************************************************************************
30-
* *
31-
* Copyright (c) <YEAR> <YOUR NAME> <YOUR EMAIL> *
32-
* *
33-
* This file is part of FreeCAD. *
34-
* *
35-
* FreeCAD is free software: you can redistribute it and/or modify it *
36-
* under the terms of the GNU Lesser General Public License as *
37-
* published by the Free Software Foundation, either version 2.1 of the *
38-
* License, or (at your option) any later version. *
39-
* *
40-
* FreeCAD is distributed in the hope that it will be useful, but *
41-
* WITHOUT ANY WARRANTY; without even the implied warranty of *
42-
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
43-
* Lesser General Public License for more details. *
44-
* *
45-
* You should have received a copy of the GNU Lesser General Public *
46-
* License along with FreeCAD. If not, see *
47-
* <https://www.gnu.org/licenses/>. *
48-
* *
49-
***************************************************************************/
50-
```
51-
5227
## Python
5328

5429
There is no unified Python coding style agreed upon for the FreeCAD codebase: each module currently has its own style. Developers working on an existing module should format their code in the prevailing style of the module they are working in.
5530

56-
### Python Copyright Header
57-
58-
The following is the standard Python copyright header that should be included in all new Python files (and backported to files a developer is making significant changes to if they do not already have this format).
59-
60-
```python
61-
# SPDX-License-Identifier: LGPL-2.1-or-later
62-
# ***************************************************************************
63-
# * *
64-
# * Copyright (c) <YEAR> <YOUR NAME> <YOUR EMAIL> *
65-
# * *
66-
# * This file is part of FreeCAD. *
67-
# * *
68-
# * FreeCAD is free software: you can redistribute it and/or modify it *
69-
# * under the terms of the GNU Lesser General Public License as *
70-
# * published by the Free Software Foundation, either version 2.1 of the *
71-
# * License, or (at your option) any later version. *
72-
# * *
73-
# * FreeCAD is distributed in the hope that it will be useful, but *
74-
# * WITHOUT ANY WARRANTY; without even the implied warranty of *
75-
# * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
76-
# * Lesser General Public License for more details. *
77-
# * *
78-
# * You should have received a copy of the GNU Lesser General Public *
79-
# * License along with FreeCAD. If not, see *
80-
# * <https://www.gnu.org/licenses/>. *
81-
# * *
82-
# ***************************************************************************
83-
```
84-
8531
## Inline documentation
8632

8733
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.

0 commit comments

Comments
 (0)