ADR Suggestion Standardizing SPDX License Headers

[AndrewSazonov]

We already use the System Package Data Exchange (SPDX) header in our files to declare the license identifier and copyright text. I propose documenting the exact format and wording so that it is consistent across all EasyScience projects.

Additional specifications can be found here:

• https://spdx.github.io/spdx-spec/
• https://reuse.software/faq/

Based on these sources, as well as this article
https://liferay.dev/b/how-and-why-to-properly-write-copyright-statements-in-your-code,
I suggest using the following header format:

SPDX-FileCopyrightText: © {year_of_file_creation} {name_of_copyright_holder} <{contact}>
SPDX-License-Identifier: {SPDX_license_name}

Proposed conventions

1. Year of file creation

   A single {year_of_file_creation} should be used, set when the file is first created and not modified afterwards.
   This approach is recommended in the article above and seems to also be used in Scipp.

2. Name of copyright holder

   The Scipp organization uses a unified text Scipp contributors across all projects under the organization (e.g. scipp, plopp, esslivedata, essreflectometry, etc.).

   I suggest adopting the same approach for all projects under the EasyScience organization by using:

   EasyScience contributors
   

3. Contact information

   Scipp uses the GitHub organization URL as the contact reference:

   https://github.com/scipp
   

   I suggest using the equivalent URL for EasyScience:

   https://github.com/easyscience
   

Following the article mentioned above, the contact should be placed in angle brackets (< >).

Final unified header format

With these conventions, all source files under the EasyScience organization would use the following two-line header:

• Python files (.py)

  # SPDX-FileCopyrightText: © 2025 EasyScience contributors <https://github.com/easyscience>
  # SPDX-License-Identifier: BSD-3-Clause
  

• QML files (.qml)

  // SPDX-FileCopyrightText: © 2025 EasyScience contributors <https://github.com/easyscience>
  // SPDX-License-Identifier: BSD-3-Clause
  

No additional information would be required in the file header. This keeps the header simple and avoids the need to update it during development.

Individual contributions and authorship history can be tracked through the repository’s Git history.

[rozyczko]

Many projects use {year_created}–{year_last_modified} or just update to the current year on modification.
We should probably explicitly acknowledge this and explain why creation-year-only was chosen . otherwise contributors will keep “correcting” it accidentally

[AndrewSazonov]

I think the article I mentioned above (https://liferay.dev/b/how-and-why-to-properly-write-copyright-statements-in-your-code) gives a good explanation of “Why not bump the year on change?” and “Why not use a year range?”.

If we agree with that reasoning, we will of course explicitly mention it in the guidelines.

[rozyczko]

If we get contributions from other facilities which hold copyright on their work, 'EasyScience contributors' may not be legally sufficient.

[AndrewSazonov]

It seems that it is possible to use the SPDX-FileCopyrightText tag multiple times to specify different contributors. Here is an example from the REUSE specification: https://reuse.software/spec-3.3/

# SPDX-FileCopyrightText: 2016, 2018-2019 Jane Doe <jane@example.com>  
# SPDX-FileCopyrightText: 2019 Example Organisation  
#
# SPDX-License-Identifier: GPL-3.0-or-later  

If the licensing information applies only to a certain snippet rather than to the entire file, the specification suggests using SPDX snippets:

# SPDX-SnippetBegin  
# SPDX-SnippetCopyrightText: 2022 Jane Doe <jane@example.com>  
# SPDX-License-Identifier: MIT  

print("Hello, world!")

# SPDX-SnippetEnd  

[damskii9992]

I really don't want to have to have SPDX snippets flying around the code. But I suppose we can always discuss that when and if it becomes relevant. Simply having the other contributor(s) at the top of the file, with us, is a lot simpler.

[rozyczko]

Are we going to automate this process or rely on CR to catch missing strings?

Should we define explicitly which file types should have the header? Tests as well? Notebooks and example scripts?

[AndrewSazonov]

Are we going to automate this process or rely on CR to catch missing strings?

I believe we definitely need a CI check for missing or incorrectly formatted SPDX headers. Probably a small script that we can run locally via a Pixi task, and also add as an extra step in the linting/formatting workflow in CI.

Should we define explicitly which file types should have the header? Tests as well? Notebooks and example scripts?

I also think we should define this explicitly - otherwise people will do it inconsistently.

How about something like this:

1. All “source-like” files
   This should be the main rule. We include SPDX headers in files that are part of the distributed codebase, for example:

   • Python modules (.py)
   • QML files (.qml)
   • C/C++, Fortran, etc. (if any)

   Probably also:

   • Shell scripts (.sh)
   • Some config files (.js, etc.)

2. Tests
   I would say yes. A couple of extra lines in the header will not hurt, and tests are still part of the codebase.

3. Example scripts
   I would also say yes, especially if they are meant to be copied or adapted by users.

4. Notebooks
   I think it might be too much to require an extra SPDX cell in every notebook. I’m also not sure how other projects usually handle this.

5. Docs / Markdown / data files
   I would not add SPDX headers here. Instead, keep it simple and rely on the main LICENSE file in the repository.