# RFC: REUSE compliance plugin for PkgTemplates.jl — API, docs, and root LICENSE behavior
**URL:** https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981
**Category:** Package Management
**Tags:** pkg, licenses, pkgtemplates
**Created:** [May 4, 2026, 2:56pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981 "2026-05-04T14:56:52Z")
**Posts on this page:** 20
**Page:** 2
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 5, 2026, 3:56pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/22 "2026-05-05T15:56:41Z")
> [@goerz](#):
>
> The registrator will check for the main `LICENSE` file, and put a hard block on the registration if it cannot be found. I might worry about having to deal with more support request along the lines of “I don’t understand, my package has a license”, and/or how to retrigger a registration to update it with the correct license.
Yes, I can understand that and that’s why I will add a short section about how to reach General registry acceptance in the documentation. Note that the [`License` plugin](https://juliaci.github.io/PkgTemplates.jl/stable/user/#PkgTemplates.License) for PkgTemplates.jl does allow you to provide some file as a license and that file will override anything else.
I believe there should be symmetrical requirements?
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 5, 2026, 4:04pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/23 "2026-05-05T16:04:55Z")
> [@goerz](#):
>
> On the other hand, I think barely anyone is using REUSE, so this worry might be overblown.
Yes, and I can see a bit why. It is not greatly advertised, people get the impression that it is more of a nuisance than it is useful, and GitHub doesn’t bother really to support it.
But then — at least here in Europe — people might wonder whether it must be GitHub and companies might start to appreciate something like an SBOM provided upon entering a single command in the CLI?
---
### Author:  [@goerz](https://discourse.julialang.org/u/goerz)
#### Post date: [May 5, 2026, 4:04pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/24 "2026-05-05T16:04:57Z")
> [@gwr](#):
>
> Note that the [`License` plugin](https://juliaci.github.io/PkgTemplates.jl/stable/user/#PkgTemplates.License) for [PkgTemplates.jl](https://juliaregistries.github.io/General/packages/redirect_to_repo/PkgTemplates) does allow you to provide some file as a license
There’s nothing wrong with giving people the _option_ to use whatever `LICENSE` file they want. But the _default_ of the License plugin is `MIT`, which is _very_ registration-friendly. I’m just saying it helps if the _defaults_ allow a package to be registered without further hoops to jump through.
It’s not a bad idea to have a “main” license.
> [@gwr](#):
>
> If `LICENSES/` contains several license texts, a human reader may easily treat the root `LICENSE` file as the authoritative project license, even though the actual licensing state is described by SPDX headers
I think they kinda _should_ be able to treat the root `LICENSE` as the “authoritative” project license. It’s a good idea to have all the code covered by a relatively uniform license. And if documentation materials are covered under a different license like Creative Commons (which I agree is a good idea), those licenses should be relatively “compatible” in spirit, so that users aren’t going to overly surprised by mismatches between the root `LICENSE` and whatever fine-grained licensing might exist in the repo.
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 5, 2026, 4:06pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/25 "2026-05-05T16:06:15Z")
> [@goerz](#):
>
> But the `default` of the License plugin is `MIT`, which is _very_ registration-friendly.
```Julia
Reuse()
```
And all of a packages licensing is going to be `MIT`.
---
### Author:  [@mbauman](https://discourse.julialang.org/u/mbauman)
#### Post date: [May 5, 2026, 4:19pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/26 "2026-05-05T16:19:14Z")
If you do not intend to re-distribute _the entire repository_ under the terms of a single `LICENSE.*`, you shouldn’t invent one that’s inaccurate. Similarly, if you do not intend to accept _all contributions_ to the repository under the terms of the single `LICENSE.*`, you shouldn’t invent one.
GitHub says contributions are under [“the repository license”](https://docs.github.com/en/site-policy/github-terms/github-terms-of-service#6-contributions-under-repository-license) (or some other _affirmative_ action I’ve taken that supersedes it, like signing a CLA). If there’s _both_ a `LICENSE.md` with just one license _and_ a `REUSE.toml` with multiple `LICENSES/*`, I would not know how to interpret this. Especially since GitHub itself will happily annotate the repository if the LICENSE.md file matches some known license.
It’s not just GitHub, it’s also SBOM tools and spdx and such. They all generally look to a _single value_ for every package in a manifest. Worse than a General-incompatibilty is _the wrong license_.
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 5, 2026, 4:19pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/27 "2026-05-05T16:19:21Z")
> [@goerz](#):
>
> I think they kinda _should_ be able to treat the root `LICENSE` as the “authoritative” project license. It’s a good idea to have all the code covered by a relatively uniform license. And if documentation materials are covered under a different license like Creative Commons (which I agree is a good idea), those licenses should be relatively “compatible” in spirit, so that users aren’t going to overly surprised by mismatches between the root `LICENSE` and whatever fine-grained licensing might exist in the repo.
This is an optional package that tries to do a good job at providing full REUSE compliance in package setups right from the start. It is totally flexible and allows you to go from “everything is licensed `MIT`” to very dedicated setups, which allow you to mention trademarks for marketing material and branding or to ship dual licenses etc.
You do not have to use it—it’s an offer. 😉
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 5, 2026, 4:23pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/28 "2026-05-05T16:23:35Z")
> [@mbauman](#):
>
> If you do not intend to re-distribute _the entire repository_ under the terms of a single `LICENSE.*`, you shouldn’t invent one that’s inaccurate. Similarly, if you do not intend to accept _all contributions_ to the repository under the terms of the single `LICENSE.*`, you shouldn’t invent one.
Sorry, I am not getting what you are saying here? Do you mean `LicenseRef-...` licenses? The Reuse plugin currently will only accept these as “custom”; all other licenses are verbatim copies from `SPDX-license-list-data` (you can currently not generate a package with a depreciated license).
Can you explain, what you mean, please?
---
### Author:  [@mbauman](https://discourse.julialang.org/u/mbauman)
#### Post date: [May 5, 2026, 4:33pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/29 "2026-05-05T16:33:13Z")
> [@gwr](#):
>
> I now think the cleaner API is not a General-registry-specific switch, but two orthogonal options:
>
> ```julia-auto
> root_license::Bool = false
> strict_open_source::Bool = false
>
> ```
>
> `root_license` controls whether `Reuse` also generates a conventional root `LICENSE` file from the primary code license
This sounds like you’re considering generating repositories that, e.g., have a `REUSE.toml` that says `docs` are `CC-BY-4.0` and `src` is `MIT`, while **simultaneously** having a straightforward MIT `LICENSE.md` that contains no additional information about reuse. If I’ve misunderstood that, then my comment is irrelevant.
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 5, 2026, 4:33pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/30 "2026-05-05T16:33:58Z")
> [@mbauman](#):
>
> GitHub says contributions are under [“the repository license”](https://docs.github.com/en/site-policy/github-terms/github-terms-of-service#6-contributions-under-repository-license) (or some other _affirmative_ action I’ve taken that supersedes it, like signing a CLA). If there’s _both_ a `LICENSE.md` with just one license _and_ a `REUSE.toml` with multiple `LICENSES/*`, I would not know how to interpret this. Especially since GitHub itself will happily annotate the repository if the LICENSE.md file matches some known license.
>
> It’s not just GitHub, it’s also SBOM tools and spdx and such. They all generally look to a _single value_ for every package in a manifest. Worse than a General-incompatibilty is _the wrong license_.
Sure, but that still misses out on how code may be moving. Let’s say I verbatim copy code files (not snippets for simplicity) that you have in your GitHub repo. SPDX headers for those files will clearly state say `SPDX-License-Identifier: EUPL-1.2-or-later`.
You can write your package with that code and provide your code with a compatible license, say `AGPL-3.0-only`.
You will still need to ship both licenses according the REUSE and it is fully ok to say that “THE” code is now `AGPL-3.0-only`. But the code files that were copied will still remain `EUPL-1.2-or-later`.
It can be more complicated than what you are saying here. And REUSE helps with all of that. Not more not less.
---
### Author:  [@mbauman](https://discourse.julialang.org/u/mbauman)
#### Post date: [May 5, 2026, 4:44pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/31 "2026-05-05T16:44:00Z")
> [@gwr](#):
>
> It can be more complicated than what you are saying here. And REUSE helps with all of that. Not more not less.
No, that’s exactly my point. Repositories that manage multiple licenses _are_ complicated, and it’s a _feature_ (not a bug!) that license scanners (and General and GitHub itself) will fail to classify licenses like [SecurityAdvisories.jl/LICENSE.md at main · JuliaLang/SecurityAdvisories.jl · GitHub](https://github.com/JuliaLang/SecurityAdvisories.jl/blob/main/LICENSE.md) into a single value.
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 5, 2026, 4:45pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/32 "2026-05-05T16:45:28Z")
> [@mbauman](#):
>
> ```julia-auto
> version = 1
>
> [[annotations]]
> path = "docs/**"
> SPDX-FileCopyrightText = "Contributors"
> SPDX-License-Identifier = "CC-BY-4.0"
>
> [[annotations]]
> path = "**"
> SPDX-FileCopyrightText = "Contributors"
> SPDX-License-Identifier = "MIT"
>
> ```
That’s not how I build the `REUSE.toml`. Your definitions _overlap_, i.e., `" **"` should also cover `"docs/**"`. While it may work, I would not believe this to be proper REUSE setup.
Whenever possible, there should be SPDX headers on a _per file_ basis. This in my default setup is done for `.jl` files in `src/`, `benchmark/`, and `test/`. Documentation or something like `Project.toml` is covered by `REUSE.toml`.
You can see the standard template below (you may provide your own file for the plugin).
```TOML
# REUSE.toml
# Part of {{{PKG}}}
version = 1
# project artifacts
[[annotations]]
path = [
".gitattributes",
".gitignore",
".github/**",
".vscode/**",
".JuliaFormatter.toml",
"Project.toml",
"Manifest.toml",
"docs/make.jl",
"docs/Project.toml"
]
precedence = "closest"
SPDX-FileCopyrightText = "{{{YEAR}}} {{{AUTHORS}}}"
SPDX-License-Identifier = "{{{ARTIFACT_LICENSE}}}"
# documentation assets
[[annotations]]
path = [
"docs/src/assets/**",
]
precedence = "closest"
SPDX-FileCopyrightText = "{{{YEAR}}} {{{AUTHORS}}}"
SPDX-License-Identifier = "{{{DOCS_ASSETS_LICENSE}}}"
# documentation source texts
[[annotations]]
path = [
"{{{README}}}",
"docs/*.md",
"docs/src/**/*.md",
]
precedence = "closest"
SPDX-FileCopyrightText = "{{{YEAR}}} {{{AUTHORS}}}"
SPDX-License-Identifier = "{{{DOCS_LICENSE}}}"
```
---
### Author:  [@mbauman](https://discourse.julialang.org/u/mbauman)
#### Post date: [May 5, 2026, 4:49pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/33 "2026-05-05T16:49:02Z")
You’re missing my point totally; I’ve edited the post to remove the shoddy example toml.
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 5, 2026, 4:52pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/34 "2026-05-05T16:52:04Z")
> [@mbauman](#):
>
> No, that’s exactly my point. Repositories that manage multiple licenses _are_ complicated, and it’s a _feature_ (not a bug!) that license scanners (and General and GitHub itself) will fail to classify licenses like [SecurityAdvisories.jl/LICENSE.md at main · JuliaLang/SecurityAdvisories.jl · GitHub](https://github.com/JuliaLang/SecurityAdvisories.jl/blob/main/LICENSE.md) into a single value.
I am still not getting this? The default is `root_license=false` and there will be no single `LICENSE` or `LICENSE.md` that may be invalid.
`reuse` has no issues at all to assign all licenses in `LICENSES/` to each and every file. It by default **ignores** a `LICENSE` file.
If you set `root_license=true`, then the plugin (after implementing this add-on) will copy the `license` given as an SPDX License Expression. For this to work out, that must be a single valid SPDX License (no `WITH` exception, no `LicenseRef_...` and no `A OR B` compound statement). **That license will come verbatim from the licenses published by `SPDX` and that will be copied. So you can only mess up _after package generation_.** 😉
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 5, 2026, 4:55pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/35 "2026-05-05T16:55:17Z")
> [@mbauman](#):
>
> This sounds like you’re considering generating repositories that, e.g., have a `REUSE.toml` that says `docs` are `CC-BY-4.0` and `src` is `MIT`, while **simultaneously** having a straightforward MIT `LICENSE.md` that contains no additional information about reuse. If I’ve misunderstood that, then my comment is irrelevant.
Again, you will only have a `LICENSE` text file, if `root_license=true` (default is `false`) and that will match the license expression given as `license` for the _primary code_. This is only done, because we cannot make REUSE compatible with General registry without this.
I would ~~not~~ have included a text as given [above](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/18). And I am doing otherwise now **because of the discussion here**. What am I missing out on?
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 5, 2026, 5:03pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/36 "2026-05-05T17:03:26Z")
@mbauman Have I understood you now and clarified the issue that you raised?
---
### Author:  [@mbauman](https://discourse.julialang.org/u/mbauman)
#### Post date: [May 5, 2026, 5:12pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/37 "2026-05-05T17:12:23Z")
> [@gwr](#):
>
> I would ~~not~~ have included a text as given [above](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/18). And I am doing otherwise now **because of the discussion here**. What am I missing out on?
I fully agree with what you wrote in [post #18](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/18) above! You’re not missing anything; I’m just a different person than goerz and not a registry maintainer. I sympathize with the fact that a complicated licensing setup will incur speed bumps and maintainer burdens during registration. But my answer is **to avoid complicated licensing setups** if at all possible. PkgTemplates is all about setting folks on a happy path, and complicated licensing setups **are not a happy path** , in my very opinionated personal opinion.
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 5, 2026, 5:23pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/38 "2026-05-05T17:23:20Z")
> [@mbauman](#):
>
> I fully agree with what you wrote in [post #18](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/18) above! You’re not missing anything; I’m just a different person than goerz and not a registry maintainer. I sympathize with the fact that a complicated licensing setup will incur speed bumps and maintainer burdens during registration. But my answer is **to avoid complicated licensing setups** if at all possible. PkgTemplates is all about setting folks on a happy path, and complicated licensing setups **are not a happy path** , in my very opinionated personal opinion.
😅
Good to know! And I agree **exactly** : There should be no ambiguity and that’s one part where REUSE excels imho. Every single file will have a clear license attribution that can be seen using `reuse spdx`—if the project passes `reuse lint`.
While this may be a “collection” of totally unrelated licenses and even “custom” licenses. That’s not what we typically want!
We want to make it easier for people to _use_ things we provide. For example, documentation. Since that will be copied and consumed differently than code, using something like `CC-BY-SA-4.0` makes sense for this.
Having attribution be done on a `per file` level is not meant to lead to madness and disorder. It just should protect that file from losing that attribution simply because someone just copied it manually.
Personally, I would very much prefer to allow for pure REUSE acceptance in General. But that’s not up to me…
---
### Author:  [@goerz](https://discourse.julialang.org/u/goerz)
#### Post date: [May 5, 2026, 6:25pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/39 "2026-05-05T18:25:24Z")
> [@mbauman](#):
>
> This sounds like you’re considering generating repositories that, e.g., have a `REUSE.toml` like: [`CC-By-4.0` for `docs/ **` and `MIT` for `** `] _and_ a straightforward MIT `LICENSE.md` that contains no additional information about reuse.
That’s certainly what _I_ have in mind! (Or, beyond this exact spec, whatever expresses "MIT for code, CC for non-code, probably with file-by-file headers). Independent of this particular plugin, I think that’s more than a sensible thing to do. People gloss over the fact that a code license like `MIT` just _doesn’t make sense_ for documentation materials which are not source code. People _should_ do this kind of licensing if they don’t just want to ignore the copyright for the non-code files of the repo (which is also a pretty sensible thing to do for small projects).
However, as you point out, lots of tooling (including the General registry) _require_ a “repository license”. As long as that license also matches the fine-grained license for (approximately all of) the _code_, and as long as the fine-grained licenses for non-code aren’t _surprising_, I don’t think that’s too much of a problem.
> [@mbauman](#):
>
> some other _affirmative_ action I’ve taken that supersedes it, like signing a CLA
If you want to play things really safe, or if the fine-grained licensing _is_ surprising with respect to the main LICENSE, then you might just have to have all contributors sign such a CLA acknowledging the fine-grained licensing.
But generally, I think it’s okay (IANAL, obviously).
> [@mbauman](#):
>
> I would not know how to interpret this.
There should always be a section in the README that explains this. Would you be confused by the licensing in [GRAPE.jl](https://github.com/JuliaQuantumControl/GRAPE.jl), where I’ve played around with REUSE (`MIT` for main code, `CC-BY-4.0` for docs, and public-domain for some other files like `*.toml`, and `CI.yml`)?
At the end of the day, though, right now there is no way _not_ to have a main `LICENSE` file for registered packages. So we have to work around that fact in some sensible way, which, I agree, requires bending one’s mind a bit around the _potential_ for “ambiguity”. But the law – even copyright law – is supposed to be _reasonable_. As long as you don’t go out of your way to create confusion between REUSE and a repo-wide license, I think you’re okay.
> [@gwr](#):
>
> Personally, I would very much prefer to allow for pure REUSE acceptance in General
I don’t disagree. There _is_ a tension between fine-grained licensing and requiring a single `LICENSE`. As I’ve been trying to argue here, applying common sense should for the most part resolve that tension, but if someone wants to revamp the general registry license checks to allow for REUSE _without_ a main `LICENSE` (sounds like a job for Claude, maybe?), that would change and potentially clarify things. At least as far as the registry is concerned. There’s probably plenty of other tools still built around the expectation of a single “repository license”, so realistically we might just have to be okay with the idea of a “main license”, even in the presence of fine-grained licensing.
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 5, 2026, 6:57pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/40 "2026-05-05T18:57:19Z")
> [@goerz](#):
>
> As I’ve been trying to argue here, applying common sense should for the most part resolve that tension, but if someone wants to revamp the general registry license checks to allow for REUSE _without_ a main `LICENSE` (sounds like a job for Claude, maybe?), that would change and potentially clarify things. At least as far as the registry is concerned.
Are you guys open for something like that? Given that the `reuse` tooling is available for CI use, once it‘s clear that a package is REUSE-compliant, things should be doable from SPDS expression parsing after collecting `reuse spdx` results, which should output the license expressions for all files (these might even be collected according to their paths…).
In the end, something like REUSE should not introduce more maintenance burden, but instead help with making things just more transparent and clear.
What about the `strict_foss` (or `strict_open_source`) idea? I know that you currently only check `code`. But if we know about documentation, specs, or data licensing as well, wouldn‘t it make sense to at least complain if `CC-BY-NC-4.0` is mixed with say an `MIT` license?
---
### Author:  [@goerz](https://discourse.julialang.org/u/goerz)
#### Post date: [May 5, 2026, 7:17pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/41 "2026-05-05T19:17:05Z")
> [@gwr](#):
>
> Are you guys open for something like that?
I would be, but I’m not really that close with the actual registry tooling (as in: I wouldn’t be the one reviewing that PR). @dilumaluthge or @GunnarFarneback would probably be better to give you an initial opinion on that.
Registry tooling moves very slowly though, so even if something like that gets merged, it can be quite a while before it actually gets deployed. Understandably, we don’t want to screw up something as central to the ecosystem as package registration
[Previous page](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981.md?page=1)
[Next page](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981.md?page=3)