# 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:** 1
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [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/1 "2026-05-04T14:56:52Z")
I have a **preview implementation** of a [`Reuse`](https://reuse.software) plugin for PkgTemplates.jl and would appreciate testing and feedback.
**Current PR:**
[Add REUSE plugin support by gwr-de · Pull Request #528 · JuliaCI/PkgTemplates.jl · GitHub](https://github.com/JuliaCI/PkgTemplates.jl/pull/528)
**Documentation preview:**
- Plugin API documentation:
[User Guide · PkgTemplates.jl](https://bsl-support.de/pkgtemplates-reuse-preview/user/#PkgTemplates.Reuse)
- User guide section:
[User Guide · PkgTemplates.jl](https://bsl-support.de/pkgtemplates-reuse-preview/user/#REUSE-compliant-Packages)
The **plugin generates** a REUSE-style licensing layout for new packages:
- `REUSE.toml` in the project root,
- required license and exception texts, verbatim, in `LICENSES/`,
- support for SPDX license expressions such as `MIT OR Apache-2.0` and `GPL-3.0-or-later WITH Classpath-exception-2.0`,
- different license expressions for primary code, project artifacts, documentation, and documentation assets; if left at `nothing`, these currently fall back to `"MIT"` matching the current PkgTemplates.jl default,
- support for custom `LicenseRef-*` licenses via a user-supplied directory; these may also be rendered as templates,
- SPDX headers for generated files where appropriate,
- optional `README.md` `## Licensing` section,
- optional `reuse lint` job in generated GitHub Actions workflows.
**I am especially interested in feedback on:**
1. Is the public API understandable?
2. Are the defaults reasonable for ordinary Julia packages?
3. Is the distinction between the existing `License` plugin and the new `Reuse` plugin clear?
4. Are the docs clear enough for users who know SPDX identifiers but have not used REUSE before?
5. Should the plugin optionally generate a conventional root `LICENSE` file for compatibility with GitHub/JOSS/human expectations?
6. Is vendoring an SPDX license-data snapshot an acceptable tradeoff for deterministic, clearly versioned, offline package generation, or should this be split out / reduced?
**For the root `LICENSE` question** (also see [this issue](https://github.com/JuliaRegistries/RegistryCI.jl/issues/581#event-5144353291)), my current inclination is:
- REUSE layout only as the default;
- optional root `LICENSE` only for simple single-license cases such as `MIT` or `Apache-2.0`;
- no full root `LICENSE` for compound expressions, expressions with exceptions, or `LicenseRef-*` cases, where the authoritative information should remain in `REUSE.toml` and `LICENSES/`.
Testing with real package templates would be very helpful.
The source branch is visible from the PR; direct branch link if useful:
[GitHub - bslMS/PkgTemplates.jl at feature/reuse-plugin · GitHub](https://github.com/bslMS/PkgTemplates.jl/tree/feature/reuse-plugin)
---
### Author:  [@goerz](https://discourse.julialang.org/u/goerz)
#### Post date: [May 4, 2026, 3:04pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/2 "2026-05-04T15:04:55Z")
> [@gwr](#):
>
> **For the root `LICENSE` question** , my current inclination is:
>
> - REUSE layout only as the default;
As we talked about [in the other thread](https://discourse.julialang.org/t/package-licenses-contemplations-and-considerations/117922/128), that’s not workable, and shouldn’t even be an option: all Julia packages (at least all registered ones) _must_ have a main `LICENSE` file, independent of what is set up via `REUSE`. The template should ensure that the REUSE information for the `.jl` files in `src` and `test` match that main `LICENSE`.
In particular, you can probably probably have `MIT` as the main `LICENSE` together with `MIT OR Apache-2.0` in REUSE, but you cannot have a registered Julia package that is only licensed under `GPL-3.0-or-later WITH Classpath-exception-2.0`. That’s assuming that this modified license cannot be put in the main `LICENSE` file and be recognized as “OSI approved”.
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 4, 2026, 3:11pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/3 "2026-05-04T15:11:29Z")
> [@goerz](#):
>
> all Julia packages (at least all registered ones) _must_ have a main `LICENSE` file, independent of what is set up via `REUSE`
Thanks, that is a useful distinction, but I would not want to make General-registry compatibility the only supported mode of the plugin.
`Reuse` is meant to generate REUSE-compliant licensing metadata for Julia projects in general. Not every Julia project generated with PkgTemplates.jl is necessarily intended for registration in General: there are private packages, internal packages, monorepo packages, application packages, teaching/research packages, and packages intended for other registries.
So I agree with the narrower point:
- for General-registry-oriented templates, the generated project should have a conventional main `LICENSE` file;
- the REUSE metadata for `src/ **/*.jl` and `test/** /*.jl` should match the primary code license represented by that file.
But I would still like the plugin to support the broader REUSE case. In my view, the right design is not “always require a root `LICENSE`”, but rather to distinguish REUSE compliance from General registry compatibility.
---
### Author:  [@goerz](https://discourse.julialang.org/u/goerz)
#### Post date: [May 4, 2026, 3:13pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/4 "2026-05-04T15:13:05Z")
Fair enough, but I would strongly suggest using “General registry compatible” as the default choice
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 4, 2026, 3:16pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/5 "2026-05-04T15:16:21Z")
That is a good point and we might have `general_registry_compliance = true` as a default for an additional switch and then the plugin can use the metadata in the snapshot (`data/spdx-license-data/licenses.json`) and expression parsing to fail — or at least warn — if violated and to generate the required `LICENSES` copy from `LICENSES/`?
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 4, 2026, 3:23pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/6 "2026-05-04T15:23:58Z")
> [@goerz](#):
>
> “General registry compatible”
Out of curiosity, what about this PR then?
[AutoMerge: support REUSE-compatible LICENSES directories by DilumAluthge-LLM · Pull Request #670 · JuliaRegistries/RegistryCI.jl · GitHub](https://github.com/JuliaRegistries/RegistryCI.jl/pull/670)
I had believed that it might allow for multiple licenses in a `LICENSES/` directory?
---
### Author:  [@goerz](https://discourse.julialang.org/u/goerz)
#### Post date: [May 4, 2026, 3:28pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/7 "2026-05-04T15:28:36Z")
If that draft ever gets finished / merged / deployed in General, that would be an entirely different story.
I’m certainly not opposed to actual full `REUSE` support for registered packages, although it might be a bit non-trivial to actually verify that fine-grained licensing includes OSI-approved licenses for all files distributed via the package servers. Maybe @dilumaluthge can give more details about the status of that PR.
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 4, 2026, 3:42pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/8 "2026-05-04T15:42:26Z")
> [@goerz](#):
>
> it might be a bit non-trivial to actually verify that fine-grained licensing includes OSI-approved licenses for all files distributed via the package servers
But isn’t that exactly where REUSE becomes especially useful?
1. `reuse lint` makes sure that there is no file that is not covered by the licenses provided in `LICENSES/` and these must match _exactly_ (e.g., you cannot have more than used in any license expression),
2. For OSI approval check one might take a strict stance:
– do not allow any `LicenseRef-...` file,
– do not allow any exception,
– for all licenses `isOSIapproved` must be `true` (contained in `SPDX-license-list-data` metadata `.json`)
Since the snapshot copies files verbatim, you can also check whether standard licenses have been modified using hashes. REUSE FAQ strongly advise against any such modification.
---
### Author:  [@goerz](https://discourse.julialang.org/u/goerz)
#### Post date: [May 4, 2026, 3:53pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/9 "2026-05-04T15:53:35Z")
> [@gwr](#):
>
> For OSI approval check one might take a strict stance
Yeah, that’s an option, but probably not what you’d actually want. The whole point of fine-grained licensing would be to allow for things like dual-licensing, including dual licensing with one OSI-compatible license and one non-OSI-compatible licensing. This comes up occasionally when government employees of certain countries maintain packages, where they are legally obligated to put their work in the public domain in certain jurisdictions, and sometimes that “public domain” is enforced with a specific non-OSI-compatible license text. In order for such a package to be registered, it must be dual-licensed. A full REUSE-aware registrator would have to pull all of that apart, and check that all relevant files are covered under at least one OSI-compatible license, but allow for additional non-compatible licenses. That’s where things might become “non-trivial”
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 4, 2026, 4:06pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/10 "2026-05-04T16:06:19Z")
So something like:
```markdown
SPDX-License-Identifier: MIT OR LicenseRef-Gov-Public-Domain
```
is what you are saying? (here we cannot use my simple check)
That seems mechanically checkable once the SPDX expression has been parsed into a normalized expression.
For a first conservative RegistryCI rule, one could evaluate each file’s effective SPDX expression as a Boolean expression:
- standard SPDX license with `isOsiApproved == true` → `true`;
- non-OSI license or `LicenseRef-*` → `false`;
- `OR` → Boolean OR;
- `AND` → Boolean AND;
- `WITH` exceptions could initially be treated as `false`, or later handled by a separate allow-list / known-SPDX-exception policy.
Then `MIT OR LicenseRef-X` evaluates to `true`, while `MIT AND LicenseRef-X` evaluates to `false`.
So the rule would not have to be “all mentioned licenses must be OSI-approved”. It could instead be: every distributed file must have at least one complete OSI-approved licensing path.
(The [plugin tooling returns SPDX AST](https://bsl-support.de/pkgtemplates-reuse-preview/developer/#SPDX-Support-Internals) for SPDX license expressions…).
---
### Author:  [@goerz](https://discourse.julialang.org/u/goerz)
#### Post date: [May 4, 2026, 4:30pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/11 "2026-05-04T16:30:45Z")
> [@gwr](#):
>
> So something like:
>
> ```julia-auto
> SPDX-License-Identifier: MIT OR LicenseRef-Gov-Public-Domain
>
> ```
>
> is what you are saying?
Yes, exactly
> [@gwr](#):
>
> That seems mechanically checkable once the SPDX expression has been parsed into a normalized expression.
>
> For a first conservative RegistryCI rule, […]
It’s definitely _possible_, and I think it would be neat to have… but all of that is what’s approaching “non-trivial” in my book, compared to checking a single `LICENSE` file. Someone “just” has to implement that. I haven’t looked at the existing draft PR in much detail, but I don’t think it covers much ground yet
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 4, 2026, 4:45pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/12 "2026-05-04T16:45:35Z")
> [@goerz](#):
>
> It’s definitely _possible_, and I think it would be neat to have… but all of that is what’s approaching “non-trivial” in my book, compared to checking a single `LICENSE` file.
Yes, agreed: the full RegistryCI problem is more than expression parsing.
What I wanted to point out is narrower: the “is there at least one OSI-approved licensing path?” part becomes quite tractable once the effective SPDX expression for a file has been resolved.
The PR already contains [SPDX expression tooling](https://bsl-support.de/pkgtemplates-reuse-preview/developer/#SPDX-Support-Internals) for the `Reuse` plugin, because the plugin needs to parse expressions, collect referenced licenses/exceptions, and normalize them. Internally this is represented as an AST, not just as a string. That AST could support the Boolean-style policy check sketched above.
So I would see the split roughly as:
1. REUSE resolution: determine the effective license expression for each distributed file.
2. SPDX expression analysis: parse/evaluate the expression against an OSI-approval predicate.
3. Registry policy: decide what General accepts, e.g. root `LICENSE`, `LicenseRef-*`, exceptions, generated files, etc.
My PR mostly covers (2) for package generation purposes, and (1) partially insofar as it generates the metadata. It does not claim to solve the full RegistryCI side, but perhaps the SPDX expression support could be useful if such a checker is developed?
---
### Author:  [@dilumaluthge](https://discourse.julialang.org/u/dilumaluthge)
#### Post date: [May 4, 2026, 4:55pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/13 "2026-05-04T16:55:53Z")
To temper expectations here, that PR is just an experiment where I was playing around with Codex. I wouldn’t read too much into the existence of it (and indeed I might close it soon).
From the standpoint of the General registry, I don’t anticipate any changes to our license checking approach in the near future.
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 4, 2026, 5:00pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/14 "2026-05-04T17:00:09Z")
> [@dilumaluthge](#):
>
> From the standpoint of the General registry, I don’t anticipate any changes to our license checking approach in the near future.
Thanks, that clarification helps.
Then I will not treat that RegistryCI PR as an indication of an active direction toward REUSE-aware registry checks.
For the PkgTemplates.jl `Reuse` plugin, I think the practical conclusion is:
- it should support full REUSE-style metadata generation for Julia projects in general;
- for packages intended for General, it should make it easy to generate/keep a conventional root `LICENSE` file consistent with the primary code license;
- RegistryCI-side validation of full REUSE metadata can remain out of scope unless there is later interest.
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 4, 2026, 6:20pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/15 "2026-05-04T18:20:58Z")
To come to a closure here. I would add the following switch to the plugin:
```julia-auto
general_registry_licensing::Bool = true
Whether to apply a conservative licensing layout intended to
match current Julia General registry expectations.
```
When `true` (default), `Reuse` generates a conventional root `LICENSE` file from the primary code `license` and requires that the primary code license can be represented unambiguously by a single standard SPDX license identifier, which has `isOsiApproved` set to `true` in the SPDX metadata.
_Documentation, documentation assets,_ or _project artifacts_ may have compound expressions, as long as there are no `WITH`exceptions in `LICENSES/` and all standard SPDX license texts copied there have `isOsiApproved` set to `true` as well; i.e. no custom `LicenseRef-*` licenses.
When `false`, `Reuse` does not apply this General-registry-oriented licensing restriction. This allows broader REUSE layouts, including compound SPDX expressions and custom `LicenseRef-*` licenses.
@goerz @dilumaluthge would a package that is generated and kept in such a way be acceptable for the General registry?
---
### Author:  [@goerz](https://discourse.julialang.org/u/goerz)
#### Post date: [May 4, 2026, 6:35pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/16 "2026-05-04T18:35:56Z")
I think so? The registrator (for the foreseeable future) only looks at the main LICENSE file. We do not, and will not, do anything beyond that simple check when determining whether a package is “acceptable for the General registry”. Ultimately, licensing is the responsibility of the submitting author. Or, in this case, maybe you as the author of the template from which they generated the package. We won’t be looking for contradictory licensing, although anyone may manually block a registration if they happen to stumble upon any obvious contradictions or license shenanigans that would raise issues with redistribution.
---
### Author:  [@tecosaur](https://discourse.julialang.org/u/tecosaur)
#### Post date: [May 5, 2026, 3:34am UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/17 "2026-05-05T03:34:57Z")
REUSE itself mentions `/LICENSE` files in it’s FAQ under “traditional licensing”, and to paraphrase, it currently says “why not just do both?”.
I think making it easier to follow REUSE standards in Julia packages is a great idea; I don’t think this motivates any immediate changes to how General handles licenses at the moment — we can just do both (REUSE and what General expects).
This seems to be how this thread is converging anyway, so I may not be adding much of value, but that’s my 2c 🙂
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 5, 2026, 9:15am UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/18 "2026-05-05T09:15:18Z")
> [@tecosaur](#):
>
> REUSE itself mentions `/LICENSE` files in it’s FAQ under “traditional licensing”, and to paraphrase, it currently says “why not just do both?”.
Yes, pragmatically we can do both for Julia packages intended for General. That is also what I would implement as the default.
But I do not think this is conceptually neutral. Once a project uses REUSE to describe file-level licensing, a conventional root `LICENSE` file becomes a coarse compatibility artifact. 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, `REUSE.toml`, and `LICENSES/`.
In a fully REUSE-oriented setup with multiple licenses, I would rather expect a root `LICENSE` file to be a pointer, e.g.
```julia-auto
LICENSE
"This project is REUSE-compliant.
See LICENSES/, SPDX headers, and REUSE.toml for actual licensing."
```
But I understand that this would not satisfy current General registry expectations.
A future RegistryCI check could in principle go further and check whether each distributed file has an OSI-approved licensing path, as [sketched above](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/10). I understand that this is not likely to happen immediately, but it remains the technically cleaner model in my opinion.
---
### Author:  [@gwr](https://discourse.julialang.org/u/gwr)
#### Post date: [May 5, 2026, 3:18pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/20 "2026-05-05T15:18:56Z")
One final design thought from this discussion.
I now think the cleaner API is not a General-registry-specific switch, but two orthogonal options:
```julia
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. The default would be `false`, because a pure REUSE layout uses `REUSE.toml`, SPDX headers, and `LICENSES/` as the licensing metadata. Setting `root_license=true` would be the compatibility path for tools, humans, or registries that expect a conventional root license file.
`strict_open_source` controls whether the configured license expressions are checked against the bundled SPDX metadata. When set to `true`, the primary code license must use standard SPDX licenses with `isOsiApproved=true`. For documentation, documentation assets, and project artifacts, standard SPDX licenses with either `isOsiApproved=true` or `isFsfLibre=true` would be accepted. This reflects that documentation, specs, and data [should not necessarily use source-code licenses](https://www.linuxfoundation.org/licensebestpractices).
PkgTemplates.jl never states that it creates packages specifically for General, nor does the `License` plugin document that selected licenses need to be OSI-approved. That is ultimately up to the General registry and to users making licensing decisions for their own projects. The `Reuse` plugin simply assists users in setting up a REUSE-compliant project layout right from the start; it should not impose silent licensing assumptions upon them.
(I will explicit add General registry guidance as part of the documentation.)
---
### Author:  [@goerz](https://discourse.julialang.org/u/goerz)
#### Post date: [May 5, 2026, 3:52pm UTC](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981/21 "2026-05-05T15:52:09Z")
> [@gwr](#):
>
> The default would be `false`
As I said before, I would strongly recommend making the default `true`. But I have no involvement in `PkgTemplates`, so presumably that choice is between you and the maintainers of `PkgTemplates` reviewing your PR.
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.
On the other hand, I think barely anyone is using REUSE, so this worry might be overblown.
[Next page](https://discourse.julialang.org/t/rfc-reuse-compliance-plugin-for-pkgtemplates-jl-api-docs-and-root-license-behavior/136981.md?page=2)