Script documentation: run addheader on new files via pre-commit

[mxmehl]

@carmenbianca desires a feature that somehow automatically takes care of adding REUSE headers to new files, ideally via a pre-commit hook. Ideally, this would also be configurable per repo, as mentioned in #68.

The tool maintainers agreed that this should not be included in the tool itself, because there are a number of difficulties:

• Users of this feature may overwrite existing headers (see the discussion in reuse addheader destroys content #338)
• They may also introduce false information that does not match the actual copyright/licensing of the project or file that's added. Example: a users pastes a file from a different project under different copyright/license that does not carry REUSE information yet. Such an automatic hook would out false info on this file!

Instead, we should document how developers could do this in the scripts documentation. while making the aware of the potential issues.

[kbroch-rivosinc]

I am wondering if there is a possibility to reconsider this:

The tool maintainers agreed that this should not be included in the tool itself, because there are a number of difficulties:

I'm finding this rivosinc#1 very useful on projects I convert to reuse compliance. After I go through the manual process of annotating the headers, I know the rule(s) of the project and I want to apply those in the future by setting them up in the .pre-commit-config.yaml file. IMO this automation is less error prone than relying on humans to apply reuse annotate manually based of some documentation. (and any script I create would simple apply the same rules as the pre-commit hook but add more code and complexity to my projects).

[nicorikken]

@kbroch-rivosinc thanks for commenting and writing that pre-commit hook! The main concern with automated annotations is the risk of it being incorrect and eventually being published as the truth.

Looking at the PR you linked, it seems that the user still needs to configure the pre-commit hook to add copyright and license properties. One could argue that this is similar to some wildcard matching based on a .reuse/dep5 file where the annotation is also automatic. Actually using the pre-commit hook would make it even more explicit because it would be pre-commit (!) so there is a manual review before committing. This is less explicit when committing files in certain directories.

Still I think we should add plenty of warnings to communicate that there is no guarantee for correctness if applied automatically.

Interested to hear what others think.

[nicorikken]

Regarding the pre-commit hook, having a mechanism for defaults would be necessary, as discussed in #68 (comment) because that would allow users to set their own default annotations. This is a better practice than setting project-specific default annotations.

So we consider annotation defaults as discussed in #68 a dependency for moving this forward. But we think then having a pre-commit hook with annotations can make sense. We agree that having this mechanism in place would be a great usability improvement.

[MarcelKoch]

Hi, I just wanted to add that we would also like to use this kind of automation (ideally the pre-commit hook) in our ginkgo project (ginkgo-project/ginkgo#1460). Currently, we add a local hook for that.

[carmenbianca]

This is still on the todo list. With a little luck it will be worked on in the coming months.

[xenoterracide]

I'm using for a java project... just started using "reuse" because, spotless argh, anyways, shared the whole thing for what I have right now to allow people to have a more thorough understanding of combining it with other tools.

# SPDX-FileCopyrightText: Copyright © 2024 Caleb Cushing
#
# SPDX-License-Identifier: CC0-1.0

# .lintstagedrc.yml
"*.java":
  - "reuse annotate --license 'Apache-2.0' --copyright 'Caleb Cushing' --copyright-prefix spdx-string-symbol --merge-copyrights"
  - &prettier "prettier --cache --ignore-unknown --write"
"*.gradle.kts":
  - &mit "reuse annotate --license 'MIT' --copyright 'Caleb Cushing' --copyright-prefix spdx-string-symbol --merge-copyrights --skip-unrecognised"
  - ktlint --format
"*.md":
  - "reuse annotate --license 'CC-BY-NC-4.0' --copyright 'Caleb Cushing' --copyright-prefix spdx-string-symbol --merge-copyrights"
  - *prettier
"*.xml":
  - "reuse annotate --license 'CC0-1.0' --copyright 'Caleb Cushing' --copyright-prefix spdx-string-symbol --merge-copyrights"
  - *prettier
"gradle-wrapper.jar":
  - "reuse annotate --license 'Apache-2.0' --copyright 'Gradle, Inc' --copyright-prefix spdx-string-symbol --merge-copyrights --skip-unrecognised gradle/wrapper/gradle-wrapper.jar"
"!(*.java|*.gradle.kts|*.md|*.xml|*.jar|*.license)":
  - *mit
  - *prettier