feature: support SPDX file tags

[adam-moss]

Is your feature request related to a problem? Please describe.

Specifying license and copyright in source files in always an interesting challenge, more so if you want to consume that information elsewhere through automation without ambiguity.

Describe the solution you'd like

Currently shellman specifies \license and \copyright for this information. It would be useful if it (and by extension mkdocs-shell also recognised the associated SPDX file tags SPDX-license-identifier: and SPDX-FileCopyrightText:.

Describe alternatives you've considered

Duplicating both and / or omitting the shellman equivalent.

Additional context

SPDX File Tags reference: https://spdx.github.io/spdx-spec/v2.3/file-tags/

[pawamoy]

Hi @adam-moss, thanks for the feature request.

I have glanced at the document you linked, but couldn't find an example where SPDX-license-identifier or SPDX-FileCopyrightText tags are used within a shell script. Are they supposed to be comments at the top of the file? Could you provide such an example here :pray:?

[adam-moss]

I have glanced at the document you linked, but couldn't find an example where SPDX-license-identifier or SPDX-FileCopyrightText tags are used within a shell script. Are they supposed to be comments at the top of the file? Could you provide such an example here 🙏?

Yes, they'd just be comments at the top of the file. So instead of / as an alternative to ## \license MIT you'd have ## SPDX-License-Identifier: MIT

Real examples you can see at e.g. https://github.com/hashicorp/terraform/blob/main/scripts/build.sh (in fact hashicorp have a tool specifically to add these tags https://github.com/hashicorp/copywrite)

[pawamoy]

Thanks!

So, would you advocate for shellman to support reading double-# comments like ## SPDX-License-Identifier: MIT, or single-# comments like # SPDX-License-Identifier: MIT? Or both?

I think I'd tend towards supporting only the single-# version, because that's surely what all other tools will expect. Supporting the double-# version wouldn't make sense if we're the only ones able to parse it.

Shellman currently filters out every line that doesn't start with ##, but I would be OK to add a special case to grep for these SPDX comments. It won't impact perfs and it's probably simple enough to implement.

We could start by supporting SPDX-license-identifier and SPDX-FileCopyrightText and later see if more tags need to be supported.

WDYT? :relaxed:

[adam-moss]

I agree the single comment would be more aligned to wider tooling so would be the preferred option.

There are slight variations of the latter, SPDX-SnippetCopyrighText for example, but I haven't seen a lot of use of those personally so I think it would be ok to ignore and stick with the 2 identified 👍