[Feat] docs: adding SPDX License IDs to the source code

[neteler]

SPDX License IDs are standardized short identifiers used to accurately and concisely identify the licenses associated with open source software (https://spdx.dev/learn/overview/). These identifiers are important for several reasons:

• Precision and clarity: They eliminate ambiguity in license identification and provide a clear and consistent way to express licensing information.
• Machine Readability: SPDX License IDs are easily processed automatically, facilitating license compliance checks and software composition analysis.
• Language neutrality: Identifiers work across programming languages and file formats
• Portability: License information travels with the source code, ensuring clarity even when files are separated from their original project context.
• Standardization: As part of the SPDX specification (now an ISO standard), these identifiers promote a universal approach to license documentation.
• Efficiency: They reduce the need for lengthy license headers in source files, making codebases more readable and manageable.

History 1: GRASS GIS going GPL 2+

In the GRASS GIS project, we had made a major effort over several years to prepare (i.e., clean up the source code) and release the GRASS IS software under GPL-2.0-or-later in 1999:

• 1999: GPL 2 or later license statement added to most files (while preserving other existing FOSS licenses for included code).
• 2000: Identification of license-incompatible code
• 2003: Identification of additional license-incompatible code

See also the history of commits at https://github.com/OSGeo/grass-legacy/.

History 2: GRASS GIS becoming a founding member of OSGeo

To become a founding member of OSGeo, we went into the https://wiki.osgeo.org/wiki/GRASS_Incubation_Progress, which took us and the mentor two years to complete due to the code review process (see https://wiki.osgeo.org/wiki/GRASS_Provenance_Review).

What would it look like?

Essentially it will be sufficient to add a single line to the headers. Random example:

diff --git a/lib/gis/plot.c b/lib/gis/plot.c
index 7cf3ac4260..be20e19807 100644
--- a/lib/gis/plot.c
+++ b/lib/gis/plot.c
@@ -21,6 +21,8 @@
  * This program is free software under the GNU General Public License
  * (>=v2). Read the file COPYING that comes with GRASS for details.
  *
+ * SPDX-License-Identifier: GPL-2.0-or-later
+ *
  * \author Original author CERL
  */

What's next

As time goes on, it makes sense to update the license entries in the files to use the SPDX License IDs. This is basically a matter of adding one more line (see also Solving License Compliance at the Source: Adding SPDX License IDs).

How to perform this:

• the REUSE tool can be a great help here, as it provides reuse annotate to add REUSE information to file headers, SPDX linting (reuse lint), etc.
• alternative: in terms of adding the SPDX one-liner, a search/replace operation might also be useful to extend the existing GPL 2+ statement.

Caveat 1:

We need to carefully check for other licenses used in the source code (e.g., MIT) and add the respective SPDX one-liner there.

Caveat 2:

The reuse annotate tool does not place it under the existing license (but I didn't read the documentation yet):

reuse annotate --license "GPL-2.0-or-later" plot.c 
Successfully changed header of plot.c

Result:

diff --git a/lib/gis/plot.c b/lib/gis/plot.c
index 7cf3ac4260..9b95621aff 100644
--- a/lib/gis/plot.c
+++ b/lib/gis/plot.c
@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+
 /*!
  * \file lib/gis/plot.c
  *

Hence a search/replace operation might be faster.

Trivia

Out of 7904 files, there are 3 with SPDX ID :-) (see here)

[echoix]

I'm really in favor of this, it would have been one of my 3 year goals otherwise ;)

About your question about having the spdx not under existing licences, if I recall correctly the convention (or requirement for tools) when using SPDX is having it really at the top. Before other human useful comments. So I don't see a problem with the output of your tool actually.

[wenzeslaus]

What about having SPDX ID as the only license information in each file instead of the longer text? I think when that was added, it was a must, but is it now?

[neteler]

What about having SPDX ID as the only license information in each file instead of the longer text?

I like this idea.

Quick check: such a change would affect around 2,000 files:

ag 'This program is free software' -l | wc -l
2245