How to satisfy both CRAN and Github license file naming requirements

Question

(NOTE: This question includes the word "license". But let's be clear: this question is not asking for licensing advice. It is asking how to simultaneously satisfy the file naming requirements of "software tools commonly used by programmers": Github and CRAN. This question could just as easily be about README files. The mere use of the word "license" seems to make folks trigger happy with their close votes.)

I have an R package who's code I'd like to keep on Github.

In accordance with R's requirements (see here for a note about template licenses), I have in my DESCRIPTION file the line:

License: MIT + file LICENCE

And my LICENCE file contains the MIT template, as required:

YEAR: 2017
COPYRIGHT HOLDER: Don Quixote

Github used to figure out licensing only by looking at the LICENSE file, which allowed me to keep the MIT text in LICENSE so that Github would detect it and the CRAN template in LICENCE so that CRAN would detect it. This approach used .Rbuildignore to hide the Github LICENSE from CRAN.

But now, a darkness has fallen on the land: Github looks at both LICENSE and LICENCE. Finding them different, it abandons its attempt to determine the project's license.

As a result, it does not seem possible to use the MIT license, or other templated licenses, in a way which satisfies both CRAN and Github.

Renaming my CRAN license template file from LICENCE to LICENCE.template would fix the issue, but then CRAN complains about a non-standard file.

I could omit a the CRAN license template file from the git repo, but then I'm not sacrificing version control for expediency.

Is there a workaround?

Theodora

You can include a license file that is listed in your .Rbuildignore file and thus present on Github but also CRAN-compliant. – Adlar

@Thomas: It's a good point! I am using .Rbuildignore to achieve CRAN compliance, but I'm loathe to use .gitignore in the same way: it's nice to have everything version controlled. But it may be necessary. – Theodora

Answer 1

There was an extended discussion on this topic in the tidyr issues (Hadley Wickham participated, which adds a little extra credibility). The solution was to use the two-line CRAN template as LICENSE (for CRAN) and then the full MIT license in LICENSE.md and add that to .Rbuildignore (for GitHub). See the relevant pull for tidyr.

This is a similar solution to the current top answer, but it feels cleaner to me as it does not use a spelling-based "hack".

Update (January 2021): As Konrad Rudolph pointed out in the comments, GitHub will now ignore LICENSE.md if LICENSE is present.

Update (August 2022): GitHub will now detect both LICENSE.md and LICENSE and will display something like "Unknown, MIT licenses found".

Subatomic

GitHub doesn’t actually support this (any longer?). GitHub defaults to a file called LICENSE, if found, and completely ignores LICENSE.md for the purpose of determining the repository license. – Mogilev

Thanks for the update! Do you know if there is a new solution? Even usethis package which is supposed to automate this type of stuff is still using the LICENSE.md approach, so that does not seem promising. – Subatomic

I suspect there isn’t a solution, to be honest. The r-lib and tidyverse packages (which in many ways represent the state of the art in R packaging) all still do what your answer suggests, and in all cases GitHub fails to figure out the correct license. – Mogilev

Answer 2

My current approach, based on Thomas's comment is as follows:

• The file LICENCE contains the MIT template license, per CRAN's requirements. It is now listed in .gitignore, so that it doesn't mess with Github.

• The file LICENSE contains the actual MIT license, per Github's requirements. It is not listed in .Rbuildignore, so that it doesn't mess with CRAN.

Of course, this is not an ideal solution because now neither CRAN nor Github is accurately archiving the whole code base. In particular, if the code is acquired from Github it is not in a state where it would be permissible to upload it to CRAN. If the code's acquired from CRAN, it would merely be non-cooperative to post it on Github (since Github would not deduce the license).

Theodora

What about putting the entire MIT license text in your LICENSE file? Then your DESCRIPTION could read 'License: file LICENSE'. It would allow Github to get things right, and it meets the requirements of R 'One of the strings ‘file LICENSE’ or ‘file LICENCE’ referring to a file named LICENSE or LICENCE in the package (source and installation) top-level directory.' I'm just not certain if CRAN would accept using a 'standard' license in that way, rather than 'MIT + file LICENSE'. – Lutyens

Answer 3

You can now follow the submission templates for CRAN and it will be supported by GitHub. For instance, this repository uses a CRAN License template and correctly shows the License on GitHub: https://github.com/TomKellyGenetics/vioplot

This is compatible with a CRAN submission. CRAN will reject a submission with the full license file rather than the template:

License components with restrictions and base license permitting such: BSD_3_clause + file LICENSE File 'LICENSE': Copyright (c) 2004, Daniel Adler All rights reserved.

Redistribution ...

Please only ship the CRAN template for the BSD_3_clause license.

This is supported by GitHub (which may have been updated). You must submit to CRAN with License: BSD_3_clause + file LICENSE (or MIT) and use only a template file such as:

YEAR: 2004
COPYRIGHT HOLDER: Daniel Adler
ORGANIZATION: University of Goettingen

Zoniazoning

That has a "view license button" but not a "hey look i'm MIT license" button as the asker probably intended – Eustasius

That's correct: this does not allow Github to automatically detect the type of the license. – Theodora

Answer 4

I actually went for a different approach; I created a subdirectory package in my project root and put everything R package-related in there. For example https://github.com/ccp-eva/eyewit

A few things I observed and did:

• First things first; I could run R CMD Check (check()) without updating anything! Everything was still working
  • This also included my unit tests
• I removed a lot of stuff from .Rbuildignore which was not needed anymore since the removed entries now live one level higher and are thus not visible to my R package anymore
• I created a license file (finally detected by GitHub)
• The only breaking change for me was the way the package needs to be installed. You need to tell devtools::install_github that your package lives in a subdirectory. You have two options (I prefer the first):
  • devtools::install_github("user/project/subdir") or
  • devtools::install_github("user/project", subdir = "subdir")

I know this is not an ideal solution but as Jenny Bryan said:

... I believe doing what's optimal for GitHub implies doing something that's unacceptable to CRAN — https://github.com/r-lib/usethis/issues/1494

UPDATE I noticed that naming the subdir package is not ideal since RStudio uses the directory’s name to display it on the top right:

.

So I changed my subdir package to my actual project name. I end up with the same name for the project root and the R project root. This is not super ideal, but I still want to satisfy both GitHub and CRAN.

[project-name]/ <- git Level
├── .git/
├── .github/
└── .gitignore
└── README.md
├── [project-name]/ <- R Project Level
│   ├── man/
│   ├── R/
│   └── tests/
│   └── project.Rproj

UPDATE 2 I observed that others had the idea before me (of course):

• https://github.com/stan-dev/rstan

Jehias